Make the crop filters accept parametric expressions.
[ffmpeg.git] / doc / filters.texi
index 9f77eee..1dc222a 100644 (file)
@@ -1,3 +1,19 @@
+@chapter Audio Filters
+@c man begin AUDIO FILTERS
+
+When you configure your FFmpeg build, you can disable any of the
+existing filters using --disable-filters.
+The configure output will show the audio filters included in your
+build.
+
+Below is a description of the currently available audio filters.
+
+@section anull
+
+Pass the audio source unchanged to the output.
+
+@c man end AUDIO FILTERS
+
 @chapter Video Filters
 @c man begin VIDEO FILTERS
 
@@ -10,34 +26,110 @@ Below is a description of the currently available video filters.
 
 @section crop
 
-Crop the input video to @var{x}:@var{y}:@var{width}:@var{height}.
+Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
 
-@example
-./ffmpeg -i in.avi -vf "crop=0:0:0:240" out.avi
-@end example
+The parameters are expressions containing the following constants:
 
-@var{x} and @var{y} specify the position of the top-left corner of the
-output (non-cropped) area.
+@table @option
+@item E, PI, PHI
+the corresponding mathematical approximated values for e
+(euler number), pi (greek PI), PHI (golden ratio)
 
-The default value of @var{x} and @var{y} is 0.
+@item x, y
+the computed values for @var{x} and @var{y}. They are evaluated for
+each new frame.
 
-The @var{width} and @var{height} parameters specify the width and height
-of the output (non-cropped) area.
+@item in_w, in_h
+the input width and heigth
 
-A value of 0 is interpreted as the maximum possible size contained in
-the area delimited by the top-left corner at position x:y.
+@item iw, ih
+same as @var{in_w} and @var{in_h}
 
-For example the parameters:
+@item out_w, out_h
+the output (cropped) width and heigth
 
+@item ow, oh
+same as @var{out_w} and @var{out_h}
+
+@item n
+the number of input frame, starting from 0
+
+@item pos
+the position in the file of the input frame, NAN if unknown
+
+@item t
+timestamp expressed in seconds, NAN if the input timestamp is unknown
+
+@end table
+
+The @var{out_w} and @var{out_h} parameters specify the expressions for
+the width and height of the output (cropped) video. They are
+evaluated just at the configuration of the filter.
+
+The default value of @var{out_w} is "in_w", and the default value of
+@var{out_h} is "in_h".
+
+The expression for @var{out_w} may depend on the value of @var{out_h},
+and the expression for @var{out_h} may depend on @var{out_w}, but they
+cannot depend on @var{x} and @var{y}, as @var{x} and @var{y} are
+evaluated after @var{out_w} and @var{out_h}.
+
+The @var{x} and @var{y} parameters specify the expressions for the
+position of the top-left corner of the output (non-cropped) area. They
+are evaluated for each frame. If the evaluated value is not valid, it
+is approximated to the nearest valid value.
+
+The default value of @var{x} is "(in_w-out_w)/2", and the default
+value for @var{y} is "(in_h-out_h)/2", which set the cropped area at
+the center of the input image.
+
+The expression for @var{x} may depend on @var{y}, and the expression
+for @var{y} may depend on @var{x}.
+
+Follow some examples:
 @example
-"crop=100:100:0:0"
+# crop the central input area with size 100x100
+crop=100:100
+
+# crop the central input area with size 2/3 of the input video
+"crop=2/3*in_w:2/3*in_h"
+
+# crop the input video central square
+crop=in_h
+
+# delimit the rectangle with the top-left corner placed at position
+# 100:100 and the right-bottom corner corresponding to the right-bottom
+# 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
+# the top and bottom borders
+"crop=in_w-2*10:in_h-2*20"
+
+# keep only the bottom right quarter of the input image
+"crop=in_w/2:in_h/2:in_w/2:in_h/2"
+
+# crop height for getting Greek harmony
+"crop=in_w:1/PHI*in_w"
+
+# 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
+"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
+"crop=in_w/2:in_h/2:y:10+10*sin(n/10)"
 @end example
 
-will delimit the rectangle with the top-left corner placed at position
-100:100 and the right-bottom corner corresponding to the right-bottom
-corner of the input image.
+@section fifo
 
-The default value of @var{width} and @var{height} is 0.
+Buffer input images and send them when they are requested.
+
+This filter is mainly useful when auto-inserted by the libavfilter
+framework.
+
+The filter does not take parameters.
 
 @section format
 
@@ -45,8 +137,8 @@ Convert the input video to one of the specified pixel formats.
 Libavfilter will try to pick one that is supported for the input to
 the next filter.
 
-The filter accepts a list of pixel format names, separated by ``:'',
-for example ``yuv420p:monow:rgb24''.
+The filter accepts a list of pixel format names, separated by ":",
+for example "yuv420p:monow:rgb24".
 
 The following command:
 
@@ -54,15 +146,75 @@ The following command:
 ./ffmpeg -i in.avi -vf "format=yuv420p" out.avi
 @end example
 
-will convert the input video to the format ``yuv420p''.
+will convert the input video to the format "yuv420p".
+
+@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.
+
+The filter supports the syntax:
+@example
+@var{filter_name}:@var{param1}:@var{param2}:...:@var{paramN}
+@end example
+
+@var{filter_name} is the name to the frei0r effect to load. If the
+environment variable @env{FREI0R_PATH} is defined, the frei0r effect
+is searched in each one of the directories specified by the colon
+separated list in @env{FREIOR_PATH}, otherwise in the standard frei0r
+paths, which are in this order: @file{HOME/.frei0r-1/lib/},
+@file{/usr/local/lib/frei0r-1/}, @file{/usr/lib/frei0r-1/}.
+
+@var{param1}, @var{param2}, ... , @var{paramN} specify the parameters
+for the frei0r effect.
+
+A frei0r effect parameter can be a boolean (whose values are specified
+with "y" and "n"), a double, a color (specified by the syntax
+@var{R}/@var{G}/@var{B}, @var{R}, @var{G}, and @var{B} being float
+numbers from 0.0 to 1.0) or by an @code{av_parse_color()} color
+description), a position (specified by the syntax @var{X}/@var{Y},
+@var{X} and @var{Y} being float numbers) and a string.
+
+The number and kind of parameters depend on the loaded effect. If an
+effect parameter is not specified the default value is set.
+
+Some examples follow:
+@example
+# apply the distort0r effect, set the first two double parameters
+frei0r=distort0r:0.5:0.01
+
+# apply the colordistance effect, takes a color as first parameter
+frei0r=colordistance:0.2/0.3/0.4
+frei0r=colordistance:violet
+frei0r=colordistance:0x112233
+
+# apply the perspective effect, specify the top left and top right
+# image positions
+frei0r=perspective:0.2/0.2:0.8/0.2
+@end example
+
+For more information see:
+@url{http://piksel.org/frei0r}
+
+@section hflip
+
+Flip the input video horizontally.
+
+For example to horizontally flip the video in input with
+@file{ffmpeg}:
+@example
+ffmpeg -i in.avi -vf "hflip" out.avi
+@end example
 
 @section noformat
 
 Force libavfilter not to use any of the specified pixel formats for the
 input to the next filter.
 
-The filter accepts a list of pixel format names, separated by ``:'',
-for example ``yuv420p:monow:rgb24''.
+The filter accepts a list of pixel format names, separated by ":",
+for example "yuv420p:monow:rgb24".
 
 The following command:
 
@@ -70,12 +222,39 @@ The following command:
 ./ffmpeg -i in.avi -vf "noformat=yuv420p, vflip" out.avi
 @end example
 
-will make libavfilter use a format different from ``yuv420p'' for the
+will make libavfilter use a format different from "yuv420p" for the
 input to the vflip filter.
 
 @section null
 
-Pass the source unchanged to the output.
+Pass the video source unchanged to the output.
+
+@section ocv_smooth
+
+Apply smooth transform using libopencv.
+
+To enable this filter install libopencv library and headers and
+configure FFmpeg with --enable-libopencv.
+
+The filter accepts 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
+the following values: "blur", "blur_no_scale", "median", "gaussian",
+"bilateral". The default value is "gaussian".
+
+@var{param1}, @var{param2}, @var{param3}, and @var{param4} are
+parameters whose meanings depend on smooth type. @var{param1} and
+@var{param2} accept integer positive values or 0, @var{param3} and
+@var{param4} accept float values.
+
+The default value for @var{param1} is 3, the default value for the
+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}
 
 @section pad
 
@@ -108,10 +287,22 @@ The default value of @var{x} and @var{y} is 0.
 Specify the color of the padded area, it can be the name of a color
 (case insensitive match) or a 0xRRGGBB[AA] sequence.
 
-The default value of @var{color} is ``black''.
+The default value of @var{color} is "black".
 
 @end table
 
+@section pixdesctest
+
+Pixel format descriptor test filter, mainly useful for internal
+testing. The output video should be equal to the input video.
+
+For example:
+@example
+format=monow, pixdesctest
+@end example
+
+can be used to test the monowhite pixel format descriptor definition.
+
 @section scale
 
 Scale the input video to @var{width}:@var{height} and/or convert the image format.
@@ -154,7 +345,10 @@ faster due to better use of the memory cache.
 
 @section unsharp
 
-Sharpen or blur the input video. It accepts the following parameters:
+Sharpen or blur the input video.
+
+It accepts the following parameters:
+@var{luma_msize_x}:@var{luma_msize_y}:@var{luma_amount}:@var{chroma_msize_x}:@var{chroma_msize_y}:@var{chroma_amount}
 
 Negative values for the amount will blur the input video, while positive
 values will sharpen. All parameters are optional and default to the
@@ -214,6 +408,85 @@ Flip the input video vertically.
 
 Below is a description of the currently available video sources.
 
+@section buffer
+
+Buffer video frames, and make them available to the filter chain.
+
+This source is mainly intended for a programmatic use, in particular
+through the interface defined in @file{libavfilter/vsrc_buffer.h}.
+
+It accepts the following parameters:
+@var{width}:@var{height}:@var{pix_fmt_string}
+
+All the parameters need to be explicitely defined.
+
+Follows the list of the accepted parameters.
+
+@table @option
+
+@item width, height
+Specify the width and height of the buffered video frames.
+
+@item pix_fmt_string
+
+A string representing the pixel format of the buffered video frames.
+It may be a number corresponding to a pixel format, or a pixel format
+name.
+
+@end table
+
+For example:
+@example
+buffer=320:240:yuv410p
+@end example
+
+will instruct the source to accept video frames with size 320x240 and
+with format "yuv410p". 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:
+@example
+buffer=320:240:6
+@end example
+
+@section color
+
+Provide an uniformly colored input.
+
+It accepts the following parameters:
+@var{color}:@var{frame_size}:@var{frame_rate}
+
+Follows the description of the accepted parameters.
+
+@table @option
+
+@item color
+Specify the color of the source. It can be the name of a color (case
+insensitive match) or a 0xRRGGBB[AA] sequence, possibly followed by an
+alpha specifier. The default value is "black".
+
+@item frame_size
+Specify the size of the sourced video, it may be a string of the form
+@var{width}x@var{heigth}, or the name of a size abbreviation. The
+default value is "320x240".
+
+@item frame_rate
+Specify the frame rate of the sourced video, as the number of frames
+generated per second. It has to be a string in the format
+@var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
+number or a valid video frame rate abbreviation. The default value is
+"25".
+
+@end table
+
+For example the following graph description will generate a red source
+with an opacity of 0.2, with size "qcif" and a frame rate of 10
+frames per second, which will be overlayed over the source connected
+to the pad with identifier "in".
+
+@example
+"color=red@@0.2:qcif:10 [color]; [in][color] overlay [out]"
+@end example
+
 @section nullsrc
 
 Null video source, never return images. It is mainly useful as a