diff options
Diffstat (limited to 'doc/filters.texi')
-rw-r--r-- | doc/filters.texi | 509 |
1 files changed, 498 insertions, 11 deletions
diff --git a/doc/filters.texi b/doc/filters.texi index a8076b2b..2ac4231 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -92,7 +92,7 @@ Follows a BNF description for the filtergraph syntax: @chapter Audio Filters @c man begin AUDIO FILTERS -When you configure your Libav build, you can disable any of the +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. @@ -155,7 +155,7 @@ tools. @chapter Video Filters @c man begin VIDEO FILTERS -When you configure your Libav build, you can disable any of the +When you configure your FFmpeg build, you can disable any of the existing filters using --disable-filters. The configure output will show the video filters included in your build. @@ -586,7 +586,7 @@ format=yuv420p:yuv444p:yuv410p Apply a frei0r effect to the input video. To enable compilation of this filter you need to install the frei0r -header and configure Libav with --enable-frei0r. +header and configure FFmpeg with --enable-frei0r. The filter supports the syntax: @example @@ -701,6 +701,223 @@ a float number which specifies chroma temporal strength, defaults to @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial} @end table +@section lut, lutrgb, lutyuv + +Compute a look-up table for binding each pixel component input value +to an output value, and apply it to input video. + +@var{lutyuv} applies a lookup table to a YUV input video, @var{lutrgb} +to an RGB input video. + +These filters accept in input a ":"-separated list of options, which +specify the expressions used for computing the lookup table for the +corresponding pixel component values. + +The @var{lut} filter requires either YUV or RGB pixel formats in +input, and accepts the options: +@table @option +@var{c0} (first pixel component) +@var{c1} (second pixel component) +@var{c2} (third pixel component) +@var{c3} (fourth pixel component, corresponds to the alpha component) +@end table + +The exact component associated to each option depends on the format in +input. + +The @var{lutrgb} filter requires RGB pixel formats in input, and +accepts the options: +@table @option +@var{r} (red component) +@var{g} (green component) +@var{b} (blue component) +@var{a} (alpha component) +@end table + +The @var{lutyuv} filter requires YUV pixel formats in input, and +accepts the options: +@table @option +@var{y} (Y/luminance component) +@var{u} (U/Cb component) +@var{v} (V/Cr component) +@var{a} (alpha component) +@end table + +The expressions can contain the following constants and functions: + +@table @option +@item E, PI, PHI +the corresponding mathematical approximated values for e +(euler number), pi (greek PI), PHI (golden ratio) + +@item w, h +the input width and heigth + +@item val +input value for the pixel component + +@item clipval +the input value clipped in the @var{minval}-@var{maxval} range + +@item maxval +maximum value for the pixel component + +@item minval +minimum value for the pixel component + +@item negval +the negated value for the pixel component value clipped in the +@var{minval}-@var{maxval} range , it corresponds to the expression +"maxval-clipval+minval" + +@item clip(val) +the computed value in @var{val} clipped in the +@var{minval}-@var{maxval} range + +@item gammaval(gamma) +the computed gamma correction value of the pixel component value +clipped in the @var{minval}-@var{maxval} range, corresponds to the +expression +"pow((clipval-minval)/(maxval-minval)\,@var{gamma})*(maxval-minval)+minval" + +@end table + +All expressions default to "val". + +Some examples follow: +@example +# negate input video +lutrgb="r=maxval+minval-val:g=maxval+minval-val:b=maxval+minval-val" +lutyuv="y=maxval+minval-val:u=maxval+minval-val:v=maxval+minval-val" + +# the above is the same as +lutrgb="r=negval:g=negval:b=negval" +lutyuv="y=negval:u=negval:v=negval" + +# negate luminance +lutyuv=negval + +# remove chroma components, turns the video into a graytone image +lutyuv="u=128:v=128" + +# apply a luma burning effect +lutyuv="y=2*val" + +# remove green and blue components +lutrgb="g=0:b=0" + +# set a constant alpha channel value on input +format=rgba,lutrgb=a="maxval-minval/2" + +# correct luminance gamma by a 0.5 factor +lutyuv=y=gammaval(0.5) +@end example + +@section mp + +Apply an MPlayer filter to the input video. + +This filter provides a wrapper around most of the filters of +MPlayer/MEncoder. + +This wrapper is considered experimental. Some of the wrapped filters +may not work properly and we may drop support for them, as they will +be implemented natively into FFmpeg. Thus you should avoid +depending on them when writing portable scripts. + +The filters accepts the parameters: +@var{filter_name}[:=]@var{filter_params} + +@var{filter_name} is the name of a supported MPlayer filter, +@var{filter_params} is a string containing the parameters accepted by +the named filter. + +The list of the currently supported filters follows: +@table @var +@item 2xsai +@item blackframe +@item boxblur +@item cropdetect +@item decimate +@item delogo +@item denoise3d +@item detc +@item dint +@item divtc +@item down3dright +@item dsize +@item eq2 +@item eq +@item field +@item fil +@item fixpts +@item framestep +@item fspp +@item geq +@item gradfun +@item harddup +@item hqdn3d +@item hue +@item il +@item ilpack +@item ivtc +@item kerndeint +@item mcdeint +@item mirror +@item noise +@item ow +@item palette +@item perspective +@item phase +@item pp7 +@item pullup +@item qp +@item rectangle +@item remove-logo +@item rgbtest +@item rotate +@item sab +@item screenshot +@item smartblur +@item softpulldown +@item softskip +@item spp +@item swapuv +@item telecine +@item test +@item tile +@item tinterlace +@item unsharp +@item uspp +@item yuvcsp +@item yvu9 +@end table + +The parameter syntax and behavior for the listed filters are the same +of the corresponding MPlayer filters. For detailed instructions check +the "VIDEO FILTERS" section in the MPlayer manual. + +Some examples follow: +@example +# remove a logo by interpolating the surrounding pixels +mp=delogo=200:200:80:20:1 + +# adjust gamma, brightness, contrast +mp=eq2=1.0:2:0.5 + +# tweak hue and saturation +mp=hue=100:-10 +@end example + +See also mplayer(1), @url{http://www.mplayerhq.hu/}. + +@section negate + +Negate input video. + +This filter accepts an integer in input, if non-zero it negates the +alpha component (if available). The default value in input is 0. + @section noformat Force libavfilter not to use any of the specified pixel formats for the @@ -728,7 +945,7 @@ Pass the video source unchanged to the output. Apply video transform using libopencv. To enable this filter install libopencv library and headers and -configure Libav with --enable-libopencv. +configure FFmpeg with --enable-libopencv. The filter takes the parameters: @var{filter_name}@{:=@}@var{filter_params}. @@ -911,9 +1128,12 @@ same as @var{out_w} and @var{out_h} x and y offsets as specified by the @var{x} and @var{y} expressions, or NAN if not yet specified -@item a +@item dar, a input display aspect ratio, same as @var{iw} / @var{ih} +@item sar +input sample aspect ratio + @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. @@ -1013,9 +1233,12 @@ the output (cropped) width and heigth @item ow, oh same as @var{out_w} and @var{out_h} -@item a +@item dar, a input display aspect ratio, same as @var{iw} / @var{ih} +@item sar +input sample aspect ratio + @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. @@ -1064,6 +1287,122 @@ scale="trunc(3/2*iw/hsub)*hsub:trunc(3/2*ih/vsub)*vsub" scale='min(500\, iw*3/2):-1' @end example +@section select +Select frames to pass in output. + +It accepts in input an expression, which is evaluated for each input +frame. If the expression is evaluated to a non-zero value, the frame +is selected and passed to the output, otherwise it is discarded. + +The expression can contain the following constants: + +@table @option +@item PI +Greek PI + +@item PHI +golden ratio + +@item E +Euler number + +@item n +the sequential number of the filtered frame, starting from 0 + +@item selected_n +the sequential number of the selected frame, starting from 0 + +@item prev_selected_n +the sequential number of the last selected frame, NAN if undefined + +@item TB +timebase of the input timestamps + +@item pts +the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in @var{TB} units, NAN if undefined + +@item t +the PTS (Presentation TimeStamp) of the filtered video frame, +expressed in seconds, NAN if undefined + +@item prev_pts +the PTS of the previously filtered video frame, NAN if undefined + +@item prev_selected_pts +the PTS of the last previously filtered video frame, NAN if undefined + +@item prev_selected_t +the PTS of the last previously selected video frame, NAN if undefined + +@item start_pts +the PTS of the first video frame in the video, NAN if undefined + +@item start_t +the time of the first video frame in the video, NAN if undefined + +@item pict_type +the picture type of the filtered frame, can assume one of the following +values: +@table @option +@item PICT_TYPE_I +@item PICT_TYPE_P +@item PICT_TYPE_B +@item PICT_TYPE_S +@item PICT_TYPE_SI +@item PICT_TYPE_SP +@item PICT_TYPE_BI +@end table + +@item interlace_type +the frame interlace type, can assume one of the following values: +@table @option +@item INTERLACE_TYPE_P +the frame is progressive (not interlaced) +@item INTERLACE_TYPE_T +the frame is top-field-first +@item INTERLACE_TYPE_B +the frame is bottom-field-first +@end table + +@item key +1 if the filtered frame is a key-frame, 0 otherwise + +@item pos +the position in the file of the filtered frame, -1 if the information +is not available (e.g. for synthetic video) +@end table + +The default value of the select expression is "1". + +Some examples follow: + +@example +# select all frames in input +select + +# the above is the same as: +select=1 + +# skip all frames: +select=0 + +# select only I-frames +select='eq(pict_type\,PICT_TYPE_I)' + +# select one frame every 100 +select='not(mod(n\,100))' + +# select only frames contained in the 10-20 time interval +select='gte(t\,10)*lte(t\,20)' + +# select only I frames contained in the 10-20 time interval +select='gte(t\,10)*lte(t\,20)*eq(pict_type\,PICT_TYPE_I)' + +# select frames with a minimum distance of 10 seconds +select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)' +@end example + @anchor{setdar} @section setdar @@ -1210,6 +1549,65 @@ settb=2*intb settb=AVTB @end example +@section showinfo + +Show a line containing various information for each input video frame. +The input video is not modified. + +The shown line contains a sequence of key/value pairs of the form +@var{key}:@var{value}. + +A description of each shown parameter follows: + +@table @option +@item n +sequential number of the input frame, starting from 0 + +@item pts +Presentation TimeStamp of the input frame, expressed as a number of +time base units. The time base unit depends on the filter input pad. + +@item pts_time +Presentation TimeStamp of the input frame, expressed as a number of +seconds + +@item pos +position of the frame in the input stream, -1 if this information in +unavailable and/or meanigless (for example in case of synthetic video) + +@item fmt +pixel format name + +@item sar +sample aspect ratio of the input frame, expressed in the form +@var{num}/@var{den} + +@item s +size of the input frame, expressed in the form +@var{width}x@var{height} + +@item i +interlaced mode ("P" for "progressive", "T" for top field first, "B" +for bottom field first) + +@item iskey +1 if the frame is a key frame, 0 otherwise + +@item type +picture type of the input frame ("I" for an I-frame, "P" for a +P-frame, "B" for a B-frame, "?" for unknown type). +Check also the documentation of the @code{AVPictureType} enum and of +the @code{av_get_picture_type_char} function defined in +@file{libavutil/avutil.h}. + +@item checksum +Adler-32 checksum of all the planes of the input frame + +@item plane_checksum +Adler-32 checksum of each plane of the input frame, expressed in the form +"[@var{c0} @var{c1} @var{c2} @var{c3}]" +@end table + @section slicify Pass the images of input video on to next video filter as multiple @@ -1225,6 +1623,21 @@ not specified it will use the default value of 16. Adding this in the beginning of filter chains should make filtering faster due to better use of the memory cache. +@section split + +Pass on the input video to two outputs. Both outputs are identical to +the input video. + +For example: +@example +[in] split [splitout1][splitout2]; +[splitout1] crop=100:100:0:0 [cropout]; +[splitout2] pad=200:200:100:100 [padout]; +@end example + +will create two separate outputs from the same input, one cropped and +one padded. + @section transpose Transpose rows with columns in the input video and optionally flip it. @@ -1329,7 +1742,7 @@ Flip the input video vertically. Deinterlace the input video ("yadif" means "yet another deinterlacing filter"). -It accepts the optional parameters: @var{mode}:@var{parity}. +It accepts the optional parameters: @var{mode}:@var{parity}:@var{auto}. @var{mode} specifies the interlacing mode to adopt, accepts one of the following values: @@ -1363,6 +1776,18 @@ Default value is -1. If interlacing is unknown or decoder does not export this information, top field first will be assumed. +@var{auto} specifies if deinterlacer should trust the interlaced flag +and only deinterlace frames marked as interlaced + +@table @option +@item 0 +deinterlace all frames +@item 1 +only deinterlace frames marked as interlaced +@end table + +Default value is 0. + @c man end VIDEO FILTERS @chapter Video Sources @@ -1378,9 +1803,10 @@ 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}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.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}:@var{scale_params} -All the parameters need to be explicitely defined. +All the parameters but @var{scale_params} need to be explicitely +defined. Follows the list of the accepted parameters. @@ -1401,6 +1827,11 @@ 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. + +@item scale_params +Specify the optional parameters to be used for the scale filter which +is automatically inserted when an input change is detected in the +input size or format. @end table For example: @@ -1415,7 +1846,7 @@ 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:1:24 +buffer=320:240:6:1:24:1:1 @end example @section color @@ -1533,7 +1964,7 @@ timebase. The expression can contain the constants "PI", "E", "PHI", Provide a frei0r source. To enable compilation of this filter you need to install the frei0r -header and configure Libav with --enable-frei0r. +header and configure FFmpeg with --enable-frei0r. The source supports the syntax: @example @@ -1555,6 +1986,49 @@ Some examples follow: frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay @end example +@section testsrc + +Generate a test video pattern, showing a color pattern, a scrolling +gradient and a timestamp. This is mainly intended for testing +purposes. + +It accepts an optional sequence of @var{key}=@var{value} pairs, +separated by ":". The description of the accepted options follows. + +@table @option + +@item size, s +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 rate, r +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". + +@item duration +Set the video duration of the sourced video. The accepted syntax is: +@example +[-]HH[:MM[:SS[.m...]]] +[-]S+[.m...] +@end example +See also the function @code{av_parse_time()}. + +If not specified, or the expressed duration is negative, the video is +supposed to be generated forever. +@end table + +For example the following: +@example +testsrc=duration=5.3:size=qcif:rate=10 +@end example + +will generate a video with a duration of 5.3 seconds, with size +176x144 and a framerate of 10 frames per second. + @c man end VIDEO SOURCES @chapter Video Sinks @@ -1562,6 +2036,19 @@ frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay Below is a description of the currently available video sinks. +@section buffersink + +Buffer video frames, and make them available to the end of the filter +graph. + +This sink is mainly intended for a programmatic use, in particular +through the interface defined in @file{libavfilter/vsink_buffer.h}. + +It does not require a string parameter in input, but you need to +specify a pointer to a list of supported pixel formats terminated by +-1 in the opaque parameter provided to @code{avfilter_init_filter} +when initializing this sink. + @section nullsink Null video sink, do absolutely nothing with the input video. It is |