@chapter Audio Filters
@c man begin AUDIO FILTERS
-When you configure your FFmpeg build, you can disable any of the
+When you configure your Libav build, you can disable any of the
existing filters using --disable-filters.
The configure output will show the audio filters included in your
build.
@chapter Video Filters
@c man begin VIDEO FILTERS
-When you configure your FFmpeg build, you can disable any of the
+When you configure your Libav build, you can disable any of the
existing filters using --disable-filters.
The configure output will show the video filters included in your
build.
@var{threshold} is the threshold below which a pixel value is
considered black, and defaults to 32.
+@section copy
+
+Copy the input source unchanged to the output. Mainly useful for
+testing purposes.
+
@section crop
Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
# corner of the input image.
crop=in_w-100:in_h-100:100:100
-# crop 10 pixels from the lefth and right borders, and 20 pixels from
+# crop 10 pixels from the left and right borders, and 20 pixels from
# the top and bottom borders
"crop=in_w-2*10:in_h-2*20"
# trembling effect
"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)"
-# erratic camera effect depending on timestamp and position
+# erratic camera effect depending on timestamp
"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)"
# set x depending on the value of y
drawbox=10:20:200:60:red@@0.5"
@end example
+@section drawtext
+
+Draw text string or text from specified file on top of video using the
+libfreetype library.
+
+To enable compilation of this filter you need to configure FFmpeg with
+@code{--enable-libfreetype}.
+
+The filter also recognizes strftime() sequences in the provided text
+and expands them accordingly. Check the documentation of strftime().
+
+The filter accepts parameters as a list of @var{key}=@var{value} pairs,
+separated by ":".
+
+The description of the accepted parameters follows.
+
+@table @option
+
+@item fontfile
+The font file to be used for drawing text. Path must be included.
+This parameter is mandatory.
+
+@item text
+The text string to be drawn. The text must be a sequence of UTF-8
+encoded characters.
+This parameter is mandatory if no file is specified with the parameter
+@var{textfile}.
+
+@item textfile
+A text file containing text to be drawn. The text must be a sequence
+of UTF-8 encoded characters.
+
+This parameter is mandatory if no text string is specified with the
+parameter @var{text}.
+
+If both text and textfile are specified, an error is thrown.
+
+@item x, y
+The offsets where text will be drawn within the video frame.
+Relative to the top/left border of the output image.
+
+The default value of @var{x} and @var{y} is 0.
+
+@item fontsize
+The font size to be used for drawing text.
+The default value of @var{fontsize} is 16.
+
+@item fontcolor
+The color to be used for drawing fonts.
+Either a string (e.g. "red") or in 0xRRGGBB[AA] format
+(e.g. "0xff000033"), possibly followed by an alpha specifier.
+The default value of @var{fontcolor} is "black".
+
+@item boxcolor
+The color to be used for drawing box around text.
+Either a string (e.g. "yellow") or in 0xRRGGBB[AA] format
+(e.g. "0xff00ff"), possibly followed by an alpha specifier.
+The default value of @var{boxcolor} is "white".
+
+@item box
+Used to draw a box around text using background color.
+Value should be either 1 (enable) or 0 (disable).
+The default value of @var{box} is 0.
+
+@item shadowx, shadowy
+The x and y offsets for the text shadow position with respect to the
+position of the text. They can be either positive or negative
+values. Default value for both is "0".
+
+@item shadowcolor
+The color to be used for drawing a shadow behind the drawn text. It
+can be a color name (e.g. "yellow") or a string in the 0xRRGGBB[AA]
+form (e.g. "0xff00ff"), possibly followed by an alpha specifier.
+The default value of @var{shadowcolor} is "black".
+
+@item ft_load_flags
+Flags to be used for loading the fonts.
+
+The flags map the corresponding flags supported by libfreetype, and are
+a combination of the following values:
+@table @var
+@item default
+@item no_scale
+@item no_hinting
+@item render
+@item no_bitmap
+@item vertical_layout
+@item force_autohint
+@item crop_bitmap
+@item pedantic
+@item ignore_global_advance_width
+@item no_recurse
+@item ignore_transform
+@item monochrome
+@item linear_design
+@item no_autohint
+@item end table
+@end table
+
+Default value is "render".
+
+For more information consult the documentation for the FT_LOAD_*
+libfreetype flags.
+
+@item tabsize
+The size in number of spaces to use for rendering the tab.
+Default value is 4.
+@end table
+
+For example the command:
+@example
+drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
+@end example
+
+will draw "Test Text" with font FreeSerif, using the default values
+for the optional parameters.
+
+The command:
+@example
+drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text':\
+ x=100: y=50: fontsize=24: fontcolor=yellow@@0.2: box=1: boxcolor=red@@0.2"
+@end example
+
+will draw 'Test Text' with font FreeSerif of size 24 at position x=100
+and y=50 (counting from the top-left corner of the screen), text is
+yellow with a red box around it. Both the text and the box have an
+opacity of 20%.
+
+Note that the double quotes are not necessary if spaces are not used
+within the parameter list.
+
+For more information about libfreetype, check:
+@url{http://www.freetype.org/}.
+
+@section fade
+
+Apply fade-in/out effect to input video.
+
+It accepts the parameters:
+@var{type}:@var{start_frame}:@var{nb_frames}
+
+@var{type} specifies if the effect type, can be either "in" for
+fade-in, or "out" for a fade-out effect.
+
+@var{start_frame} specifies the number of the start frame for starting
+to apply the fade effect.
+
+@var{nb_frames} specifies the number of frames for which the fade
+effect has to last. At the end of the fade-in effect the output video
+will have the same intensity as the input video, at the end of the
+fade-out transition the output video will be completely black.
+
+A few usage examples follow, usable too as test scenarios.
+@example
+# fade in first 30 frames of video
+fade=in:0:30
+
+# fade out last 45 frames of a 200-frame video
+fade=out:155:45
+
+# fade in first 25 frames and fade out last 25 frames of a 1000-frame video
+fade=in:0:25, fade=out:975:25
+
+# make first 5 frames black, then fade in from frame 5-24
+fade=in:5:20
+@end example
+
+@section fieldorder
+
+Transform the field order of the input video.
+
+It accepts one parameter which specifies the required field order that
+the input interlaced video will be transformed to. The parameter can
+assume one of the following values:
+
+@table @option
+@item 0 or bff
+output bottom field first
+@item 1 or tff
+output top field first
+@end table
+
+Default value is "tff".
+
+Transformation is achieved by shifting the picture content up or down
+by one line, and filling the remaining line with appropriate picture content.
+This method is consistent with most broadcast field order converters.
+
+If the input video is not flagged as being interlaced, or it is already
+flagged as being of the required output field order then this filter does
+not alter the incoming video.
+
+This filter is very useful when converting to or from PAL DV material,
+which is bottom field first.
+
+For example:
+@example
+./ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+@end example
+
@section fifo
Buffer input images and send them when they are requested.
The filter accepts a list of pixel format names, separated by ":",
for example "yuv420p:monow:rgb24".
-The following command:
-
+Some examples follow:
@example
-./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
-@end example
+# convert the input video to the format "yuv420p"
+format=yuv420p
-will convert the input video to the format "yuv420p".
+# convert the input video to any of the formats in the list
+format=yuv420p:yuv444p:yuv410p
+@end example
@anchor{frei0r}
@section frei0r
Apply a frei0r effect to the input video.
To enable compilation of this filter you need to install the frei0r
-header and configure FFmpeg with --enable-frei0r.
+header and configure Libav with --enable-frei0r.
The filter supports the syntax:
@example
Interpolate the gradients that should go where the bands are, and
dither them.
+This filter is designed for playback only. Do not use it prior to
+lossy compression, because compression tends to lose the dither and
+bring back the bands.
+
The filter takes two optional parameters, separated by ':':
@var{strength}:@var{radius}
The filter accepts a list of pixel format names, separated by ":",
for example "yuv420p:monow:rgb24".
-The following command:
-
+Some examples follow:
@example
-./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
-@end example
+# force libavfilter to use a format different from "yuv420p" for the
+# input to the vflip filter
+noformat=yuv420p,vflip
-will make libavfilter use a format different from "yuv420p" for the
-input to the vflip filter.
+# convert the input video to any of the formats not contained in the list
+noformat=yuv420p:yuv444p:yuv410p
+@end example
@section null
Pass the video source unchanged to the output.
-@section ocv_smooth
+@section ocv
-Apply smooth transform using libopencv.
+Apply video transform using libopencv.
To enable this filter install libopencv library and headers and
-configure FFmpeg with --enable-libopencv.
+configure Libav with --enable-libopencv.
+
+The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}.
+
+@var{filter_name} is the name of the libopencv filter to apply.
+
+@var{filter_params} specifies the parameters to pass to the libopencv
+filter. If not specified the default values are assumed.
+
+Refer to the official libopencv documentation for more precise
+informations:
+@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
+
+Follows the list of supported libopencv filters.
+
+@anchor{dilate}
+@subsection dilate
+
+Dilate an image by using a specific structuring element.
+This filter corresponds to the libopencv function @code{cvDilate}.
-The filter accepts the following parameters:
+It accepts the parameters: @var{struct_el}:@var{nb_iterations}.
+
+@var{struct_el} represents a structuring element, and has the syntax:
+@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
+
+@var{cols} and @var{rows} represent the number of colums and rows of
+the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
+point, and @var{shape} the shape for the structuring element, and
+can be one of the values "rect", "cross", "ellipse", "custom".
+
+If the value for @var{shape} is "custom", it must be followed by a
+string of the form "=@var{filename}". The file with name
+@var{filename} is assumed to represent a binary image, with each
+printable character corresponding to a bright pixel. When a custom
+@var{shape} is used, @var{cols} and @var{rows} are ignored, the number
+or columns and rows of the read file are assumed instead.
+
+The default value for @var{struct_el} is "3x3+0x0/rect".
+
+@var{nb_iterations} specifies the number of times the transform is
+applied to the image, and defaults to 1.
+
+Follow some example:
+@example
+# use the default values
+ocv=dilate
+
+# dilate using a structuring element with a 5x5 cross, iterate two times
+ocv=dilate=5x5+2x2/cross:2
+
+# read the shape from the file diamond.shape, iterate two times
+# the file diamond.shape may contain a pattern of characters like this:
+# *
+# ***
+# *****
+# ***
+# *
+# the specified cols and rows are ignored (but not the anchor point coordinates)
+ocv=0x0+2x2/custom=diamond.shape:2
+@end example
+
+@subsection erode
+
+Erode an image by using a specific structuring element.
+This filter corresponds to the libopencv function @code{cvErode}.
+
+The filter accepts the parameters: @var{struct_el}:@var{nb_iterations},
+with the same meaning and use of those of the dilate filter
+(@pxref{dilate}).
+
+@subsection smooth
+
+Smooth the input video.
+
+The filter takes the following parameters:
@var{type}:@var{param1}:@var{param2}:@var{param3}:@var{param4}.
@var{type} is the type of smooth filter to apply, and can be one of
other parameters is 0.
These parameters correspond to the parameters assigned to the
-libopencv function @code{cvSmooth}. Refer to the official libopencv
-documentation for the exact meaning of the parameters:
-@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
+libopencv function @code{cvSmooth}.
@section overlay
overlay=main_w-overlay_w-10:main_h-overlay_h-10
# insert a transparent PNG logo in the bottom left corner of the input
-movie=0:png:logo.png [logo];
+movie=logo.png [logo];
[in][logo] overlay=10:main_h-overlay_h-10 [out]
# insert 2 different transparent PNG logos (second logo on bottom
# right corner):
-movie=0:png:logo1.png [logo1];
-movie=0:png:logo2.png [logo2];
+movie=logo1.png [logo1];
+movie=logo2.png [logo2];
[in][logo1] overlay=10:H-h-10 [in+logo1];
[in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
It accepts the following parameters:
@var{width}:@var{height}:@var{x}:@var{y}:@var{color}.
+The parameters @var{width}, @var{height}, @var{x}, and @var{y} are
+expressions containing the following constants:
+
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), phi (golden ratio)
+
+@item in_w, in_h
+the input video width and heigth
+
+@item iw, ih
+same as @var{in_w} and @var{in_h}
+
+@item out_w, out_h
+the output width and heigth, that is the size of the padded area as
+specified by the @var{width} and @var{height} expressions
+
+@item ow, oh
+same as @var{out_w} and @var{out_h}
+
+@item x, y
+x and y offsets as specified by the @var{x} and @var{y}
+expressions, or NAN if not yet specified
+
+@item a
+input display aspect ratio, same as @var{iw} / @var{ih}
+
+@item hsub, vsub
+horizontal and vertical chroma subsample values. For example for the
+pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
+@end table
+
Follows the description of the accepted parameters.
@table @option
value for @var{width} or @var{height} is 0, the corresponding input size
is used for the output.
+The @var{width} expression can reference the value set by the
+@var{height} expression, and viceversa.
+
The default value of @var{width} and @var{height} is 0.
@item x, y
Specify the offsets where to place the input image in the padded area
with respect to the top/left border of the output image.
+The @var{x} expression can reference the value set by the @var{y}
+expression, and viceversa.
+
The default value of @var{x} and @var{y} is 0.
@item color
@end table
-For example:
+Some examples follow:
@example
# Add paddings with color "violet" to the input video. Output video
# size is 640x480, the top-left corner of the input video is placed at
-# row 0, column 40.
+# column 0, row 40.
pad=640:480:0:40:violet
+
+# pad the input to get an output with dimensions increased bt 3/2,
+# and put the input video at the center of the padded area
+pad="3/2*iw:3/2*ih:(ow-iw)/2:(oh-ih)/2"
+
+# pad the input to get a squared output with size equal to the maximum
+# value between the input width and height, and put the input video at
+# the center of the padded area
+pad="max(iw\,ih):ow:(ow-iw)/2:(oh-ih)/2"
+
+# pad the input to get a final w/h ratio of 16:9
+pad="ih*16/9:ih:(ow-iw)/2:(oh-ih)/2"
+
+# double output size and put the input video in the bottom-right
+# corner of the output padded area
+pad="2*iw:2*ih:ow-iw:oh-ih"
@end example
@section pixdesctest
Scale the input video to @var{width}:@var{height} and/or convert the image format.
-For example the command:
+The parameters @var{width} and @var{height} are expressions containing
+the following constants:
-@example
-./ffmpeg -i in.avi -vf "scale=200:100" out.avi
-@end example
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), phi (golden ratio)
+
+@item in_w, in_h
+the input width and heigth
-will scale the input video to a size of 200x100.
+@item iw, ih
+same as @var{in_w} and @var{in_h}
+
+@item out_w, out_h
+the output (cropped) width and heigth
+
+@item ow, oh
+same as @var{out_w} and @var{out_h}
+
+@item a
+input display aspect ratio, same as @var{iw} / @var{ih}
+
+@item hsub, vsub
+horizontal and vertical chroma subsample values. For example for the
+pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
+@end table
If the input image format is different from the format requested by
the next filter, the scale filter will convert the input to the
The default value of @var{width} and @var{height} is 0.
+Some examples follow:
+@example
+# scale the input video to a size of 200x100.
+scale=200:100
+
+# scale the input to 2x
+scale=2*iw:2*ih
+# the above is the same as
+scale=2*in_w:2*in_h
+
+# scale the input to half size
+scale=iw/2:ih/2
+
+# increase the width, and set the height to the same size
+scale=3/2*iw:ow
+
+# seek for Greek harmony
+scale=iw:1/PHI*iw
+scale=ih*PHI:ih
+
+# increase the height, and set the width to 3/2 of the height
+scale=3/2*oh:3/5*ih
+
+# increase the size, but make the size a multiple of the chroma
+scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub"
+
+# increase the width to a maximum of 500 pixels, keep the same input aspect ratio
+scale='min(500\, iw*3/2):-1'
+@end example
+
+@anchor{setdar}
+@section setdar
+
+Set the Display Aspect Ratio for the filter output video.
+
+This is done by changing the specified Sample (aka Pixel) Aspect
+Ratio, according to the following equation:
+@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
+
+Keep in mind that this filter does not modify the pixel dimensions of
+the video frame. Also the display aspect ratio set by this filter may
+be changed by later filters in the filterchain, e.g. in case of
+scaling or if another "setdar" or a "setsar" filter is applied.
+
+The filter accepts a parameter string which represents the wanted
+display aspect ratio.
+The parameter can be a floating point number string, or an expression
+of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
+numerator and denominator of the aspect ratio.
+If the parameter is not specified, it is assumed the value "0:1".
+
+For example to change the display aspect ratio to 16:9, specify:
+@example
+setdar=16:9
+# the above is equivalent to
+setdar=1.77777
+@end example
+
+See also the "setsar" filter documentation (@pxref{setsar}).
+
@section setpts
Change the PTS (presentation timestamp) of the input video frames.
setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
@end example
+@anchor{setsar}
+@section setsar
+
+Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
+
+Note that as a consequence of the application of this filter, the
+output display aspect ratio will change according to the following
+equation:
+@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
+
+Keep in mind that the sample aspect ratio set by this filter may be
+changed by later filters in the filterchain, e.g. if another "setsar"
+or a "setdar" filter is applied.
+
+The filter accepts a parameter string which represents the wanted
+sample aspect ratio.
+The parameter can be a floating point number string, or an expression
+of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
+numerator and denominator of the aspect ratio.
+If the parameter is not specified, it is assumed the value "0:1".
+
+For example to change the sample aspect ratio to 10:11, specify:
+@example
+setsar=10:11
+@end example
+
@section settb
Set the timebase to use for the output frames timestamps.
@section yadif
-yadif is "yet another deinterlacing filter".
+Deinterlace the input video ("yadif" means "yet another deinterlacing
+filter").
-It accepts the syntax:
-@example
-yadif=[@var{mode}[:@var{parity}]]
-@end example
-
-@table @option
-
-@item mode
-Specify the interlacing mode to adopt, accepts one of the following values.
-
-0: Output 1 frame for each frame.
+It accepts the optional parameters: @var{mode}:@var{parity}.
-1: Output 1 frame for each field.
+@var{mode} specifies the interlacing mode to adopt, accepts one of the
+following values:
-2: Like 0 but skips spatial interlacing check.
-
-3: Like 1 but skips spatial interlacing check.
+@table @option
+@item 0
+output 1 frame for each frame
+@item 1
+output 1 frame for each field
+@item 2
+like 0 but skips spatial interlacing check
+@item 3
+like 1 but skips spatial interlacing check
+@end table
Default value is 0.
-@item parity
-0 if is bottom field first, 1 if the interlaced video is top field
-first, -1 to enable automatic detection.
+@var{parity} specifies the picture field parity assumed for the input
+interlaced video, accepts one of the following values:
+@table @option
+@item 0
+assume bottom field first
+@item 1
+assume top field first
+@item -1
+enable automatic detection
@end table
+Default value is -1.
+If interlacing is unknown or decoder does not export this information,
+top field first will be assumed.
+
@c man end VIDEO FILTERS
@chapter Video Sources
through the interface defined in @file{libavfilter/vsrc_buffer.h}.
It accepts the following parameters:
-@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}
+@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}
All the parameters need to be explicitely defined.
@item timebase_num, timebase_den
Specify numerator and denomitor of the timebase assumed by the
timestamps of the buffered frames.
+
+@item sample_aspect_ratio.num, sample_aspect_ratio.den
+Specify numerator and denominator of the sample aspect ratio assumed
+by the video frames.
@end table
For example:
@example
-buffer=320:240:yuv410p:1:24
+buffer=320:240:yuv410p:1:24:1:1
@end example
will instruct the source to accept video frames with size 320x240 and
-with format "yuv410p" and assuming 1/24 as the timestamps timebase.
+with format "yuv410p", assuming 1/24 as the timestamps timebase and
+square pixels (1:1 sample aspect ratio).
Since the pixel format with name "yuv410p" corresponds to the number 6
(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),
this example corresponds to:
"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
@end example
+@section movie
+
+Read a video stream from a movie container.
+
+It accepts the syntax: @var{movie_name}[:@var{options}] where
+@var{movie_name} is the name of the resource to read (not necessarily
+a file but also a device or a stream accessed through some protocol),
+and @var{options} is an optional sequence of @var{key}=@var{value}
+pairs, separated by ":".
+
+The description of the accepted options follows.
+
+@table @option
+
+@item format_name, f
+Specifies the format assumed for the movie to read, and can be either
+the name of a container or an input device. If not specified the
+format is guessed from @var{movie_name} or by probing.
+
+@item seek_point, sp
+Specifies the seek point in seconds, the frames will be output
+starting from this seek point, the parameter is evaluated with
+@code{av_strtod} so the numerical value may be suffixed by an IS
+postfix. Default value is "0".
+
+@item stream_index, si
+Specifies the index of the video stream to read. If the value is -1,
+the best suited video stream will be automatically selected. Default
+value is "-1".
+
+@end table
+
+This filter allows to overlay a second video on top of main input of
+a filtergraph as shown in this graph:
+@example
+input -----------> deltapts0 --> overlay --> output
+ ^
+ |
+movie --> scale--> deltapts1 -------+
+@end example
+
+Some examples follow:
+@example
+# skip 3.2 seconds from the start of the avi file in.avi, and overlay it
+# on top of the input labelled as "in".
+movie=in.avi:seek_point=3.2, scale=180:-1, setpts=PTS-STARTPTS [movie];
+[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
+
+# read from a video4linux2 device, and overlay it on top of the input
+# labelled as "in"
+movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
+[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
+
+@end example
+
@section nullsrc
Null video source, never return images. It is mainly useful as a
Provide a frei0r source.
To enable compilation of this filter you need to install the frei0r
-header and configure FFmpeg with --enable-frei0r.
+header and configure Libav with --enable-frei0r.
The source supports the syntax:
@example
projects / ffmpeg / blobdiff