Merge commit '545a0b807cf45b2bbc4c9087a297b741ce00f508'
authorMichael Niedermayer <michaelni@gmx.at>
Wed, 21 Aug 2013 09:37:10 +0000 (11:37 +0200)
committerMichael Niedermayer <michaelni@gmx.at>
Wed, 21 Aug 2013 09:37:10 +0000 (11:37 +0200)
* commit '545a0b807cf45b2bbc4c9087a297b741ce00f508':
  vf_fps: add 'start_time' option

Conflicts:
doc/filters.texi
libavfilter/vf_fps.c

Merged-by: Michael Niedermayer <michaelni@gmx.at>
1  2 
doc/filters.texi
libavfilter/vf_fps.c

@@@ -2149,2081 -1221,67 +2149,2089 @@@ Set the threshold below which a pixel v
  
  @end table
  
 -Some examples follow:
 -@example
 -# convert the input video to the format "yuv420p"
 -format=pix_fmts=yuv420p
 +@section blend
  
 -# convert the input video to any of the formats in the list
 -format=pix_fmts=yuv420p|yuv444p|yuv410p
 -@end example
 +Blend two video frames into each other.
  
 -@section fps
 +It takes two input streams and outputs one stream, the first input is the
 +"top" layer and second input is "bottom" layer.
 +Output terminates when shortest input terminates.
  
 -Convert the video to specified constant framerate by duplicating or dropping
 -frames as necessary.
 +A description of the accepted options follows.
  
 -This filter accepts the following named parameters:
  @table @option
 +@item c0_mode
 +@item c1_mode
 +@item c2_mode
 +@item c3_mode
 +@item all_mode
 +Set blend mode for specific pixel component or all pixel components in case
 +of @var{all_mode}. Default value is @code{normal}.
 +
 +Available values for component modes are:
 +@table @samp
 +@item addition
 +@item and
 +@item average
 +@item burn
 +@item darken
 +@item difference
 +@item divide
 +@item dodge
 +@item exclusion
 +@item hardlight
 +@item lighten
 +@item multiply
 +@item negation
 +@item normal
 +@item or
 +@item overlay
 +@item phoenix
 +@item pinlight
 +@item reflect
 +@item screen
 +@item softlight
 +@item subtract
 +@item vividlight
 +@item xor
 +@end table
  
 -@item fps
 -Desired output framerate.
 +@item c0_opacity
 +@item c1_opacity
 +@item c2_opacity
 +@item c3_opacity
 +@item all_opacity
 +Set blend opacity for specific pixel component or all pixel components in case
 +of @var{all_opacity}. Only used in combination with pixel component blend modes.
  
 -@item start_time
 -Assume the first PTS should be the given value, in seconds. This allows for
 -padding/trimming at the start of stream. By default, no assumption is made
 -about the first frame's expected PTS, so no padding or trimming is done.
 -For example, this could be set to 0 to pad the beginning with duplicates of
 -the first frame if a video stream starts after the audio stream or to trim any
 -frames with a negative PTS.
 +@item c0_expr
 +@item c1_expr
 +@item c2_expr
 +@item c3_expr
 +@item all_expr
 +Set blend expression for specific pixel component or all pixel components in case
 +of @var{all_expr}. Note that related mode options will be ignored if those are set.
  
 -@end table
 +The expressions can use the following variables:
  
 -@anchor{frei0r}
 -@section frei0r
 +@table @option
 +@item N
 +The sequential number of the filtered frame, starting from @code{0}.
  
 -Apply a frei0r effect to the input video.
 +@item X
 +@item Y
 +the coordinates of the current sample
  
 -To enable compilation of this filter you need to install the frei0r
 -header and configure Libav with --enable-frei0r.
 +@item W
 +@item H
 +the width and height of currently filtered plane
  
 -This filter accepts the following options:
 +@item SW
 +@item SH
 +Width and height scale depending on the currently filtered plane. It is the
 +ratio between the corresponding luma plane number of pixels and the current
 +plane ones. E.g. for YUV4:2:0 the values are @code{1,1} for the luma plane, and
 +@code{0.5,0.5} for chroma planes.
  
 -@table @option
 +@item T
 +Time of the current frame, expressed in seconds.
  
 -@item filter_name
 -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/}.
 +@item TOP, A
 +Value of pixel component at current location for first video frame (top layer).
  
 -@item filter_params
 -A '|'-separated list of parameters to pass to the frei0r effect.
 +@item BOTTOM, B
 +Value of pixel component at current location for second video frame (bottom layer).
 +@end table
  
 +@item shortest
 +Force termination when the shortest input terminates. Default is @code{0}.
 +@item repeatlast
 +Continue applying the last bottom frame after the end of the stream. A value of
 +@code{0} disable the filter after the last frame of the bottom layer is reached.
 +Default is @code{1}.
  @end table
  
 -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.
 +@subsection Examples
 +
 +@itemize
 +@item
 +Apply transition from bottom layer to top layer in first 10 seconds:
 +@example
 +blend=all_expr='A*(if(gte(T,10),1,T/10))+B*(1-(if(gte(T,10),1,T/10)))'
 +@end example
 +
 +@item
 +Apply 1x1 checkerboard effect:
 +@example
 +blend=all_expr='if(eq(mod(X,2),mod(Y,2)),A,B)'
 +@end example
 +@end itemize
 +
 +@section boxblur
 +
 +Apply boxblur algorithm to the input video.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +
 +@item luma_radius, lr
 +@item luma_power, lp
 +@item chroma_radius, cr
 +@item chroma_power, cp
 +@item alpha_radius, ar
 +@item alpha_power, ap
 +
 +@end table
 +
 +A description of the accepted options follows.
 +
 +@table @option
 +@item luma_radius, lr
 +@item chroma_radius, cr
 +@item alpha_radius, ar
 +Set an expression for the box radius in pixels used for blurring the
 +corresponding input plane.
 +
 +The radius value must be a non-negative number, and must not be
 +greater than the value of the expression @code{min(w,h)/2} for the
 +luma and alpha planes, and of @code{min(cw,ch)/2} for the chroma
 +planes.
 +
 +Default value for @option{luma_radius} is "2". If not specified,
 +@option{chroma_radius} and @option{alpha_radius} default to the
 +corresponding value set for @option{luma_radius}.
 +
 +The expressions can contain the following constants:
 +@table @option
 +@item w
 +@item h
 +the input width and height in pixels
 +
 +@item cw
 +@item ch
 +the input chroma image width and height in pixels
 +
 +@item hsub
 +@item 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
 +
 +@item luma_power, lp
 +@item chroma_power, cp
 +@item alpha_power, ap
 +Specify how many times the boxblur filter is applied to the
 +corresponding plane.
 +
 +Default value for @option{luma_power} is 2. If not specified,
 +@option{chroma_power} and @option{alpha_power} default to the
 +corresponding value set for @option{luma_power}.
 +
 +A value of 0 will disable the effect.
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Apply a boxblur filter with luma, chroma, and alpha radius
 +set to 2:
 +@example
 +boxblur=luma_radius=2:luma_power=1
 +boxblur=2:1
 +@end example
 +
 +@item
 +Set luma radius to 2, alpha and chroma radius to 0:
 +@example
 +boxblur=2:1:cr=0:ar=0
 +@end example
 +
 +@item
 +Set luma and chroma radius to a fraction of the video dimension:
 +@example
 +boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chroma_power=1
 +@end example
 +@end itemize
 +
 +@section colorbalance
 +Modify intensity of primary colors (red, green and blue) of input frames.
 +
 +The filter allows an input frame to be adjusted in the shadows, midtones or highlights
 +regions for the red-cyan, green-magenta or blue-yellow balance.
 +
 +A positive adjustment value shifts the balance towards the primary color, a negative
 +value towards the complementary color.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item rs
 +@item gs
 +@item bs
 +Adjust red, green and blue shadows (darkest pixels).
 +
 +@item rm
 +@item gm
 +@item bm
 +Adjust red, green and blue midtones (medium pixels).
 +
 +@item rh
 +@item gh
 +@item bh
 +Adjust red, green and blue highlights (brightest pixels).
 +
 +Allowed ranges for options are @code{[-1.0, 1.0]}. Defaults are @code{0}.
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Add red color cast to shadows:
 +@example
 +colorbalance=rs=.3
 +@end example
 +@end itemize
 +
 +@section colorchannelmixer
 +
 +Adjust video input frames by re-mixing color channels.
 +
 +This filter modifies a color channel by adding the values associated to
 +the other channels of the same pixels. For example if the value to
 +modify is red, the output value will be:
 +@example
 +@var{red}=@var{red}*@var{rr} + @var{blue}*@var{rb} + @var{green}*@var{rg} + @var{alpha}*@var{ra}
 +@end example
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item rr
 +@item rg
 +@item rb
 +@item ra
 +Adjust contribution of input red, green, blue and alpha channels for output red channel.
 +Default is @code{1} for @var{rr}, and @code{0} for @var{rg}, @var{rb} and @var{ra}.
 +
 +@item gr
 +@item gg
 +@item gb
 +@item ga
 +Adjust contribution of input red, green, blue and alpha channels for output green channel.
 +Default is @code{1} for @var{gg}, and @code{0} for @var{gr}, @var{gb} and @var{ga}.
 +
 +@item br
 +@item bg
 +@item bb
 +@item ba
 +Adjust contribution of input red, green, blue and alpha channels for output blue channel.
 +Default is @code{1} for @var{bb}, and @code{0} for @var{br}, @var{bg} and @var{ba}.
 +
 +@item ar
 +@item ag
 +@item ab
 +@item aa
 +Adjust contribution of input red, green, blue and alpha channels for output alpha channel.
 +Default is @code{1} for @var{aa}, and @code{0} for @var{ar}, @var{ag} and @var{ab}.
 +
 +Allowed ranges for options are @code{[-2.0, 2.0]}.
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Convert source to grayscale:
 +@example
 +colorchannelmixer=.3:.4:.3:0:.3:.4:.3:0:.3:.4:.3
 +@end example
 +@item
 +Simulate sepia tones:
 +@example
 +colorchannelmixer=.393:.769:.189:0:.349:.686:.168:0:.272:.534:.131
 +@end example
 +@end itemize
 +
 +@section colormatrix
 +
 +Convert color matrix.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item src
 +@item dst
 +Specify the source and destination color matrix. Both values must be
 +specified.
 +
 +The accepted values are:
 +@table @samp
 +@item bt709
 +BT.709
 +
 +@item bt601
 +BT.601
 +
 +@item smpte240m
 +SMPTE-240M
 +
 +@item fcc
 +FCC
 +@end table
 +@end table
 +
 +For example to convert from BT.601 to SMPTE-240M, use the command:
 +@example
 +colormatrix=bt601:smpte240m
 +@end example
 +
 +@section copy
 +
 +Copy the input source unchanged to the output. Mainly useful for
 +testing purposes.
 +
 +@section crop
 +
 +Crop the input video to given dimensions.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item w, out_w
 +Width of the output video. It defaults to @code{iw}.
 +This expression is evaluated only once during the filter
 +configuration.
 +
 +@item h, out_h
 +Height of the output video. It defaults to @code{ih}.
 +This expression is evaluated only once during the filter
 +configuration.
 +
 +@item x
 +Horizontal position, in the input video, of the left edge of the output video.
 +It defaults to @code{(in_w-out_w)/2}.
 +This expression is evaluated per-frame.
 +
 +@item y
 +Vertical position, in the input video, of the top edge of the output video.
 +It defaults to @code{(in_h-out_h)/2}.
 +This expression is evaluated per-frame.
 +
 +@item keep_aspect
 +If set to 1 will force the output display aspect ratio
 +to be the same of the input, by changing the output sample aspect
 +ratio. It defaults to 0.
 +@end table
 +
 +The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
 +expressions containing the following constants:
 +
 +@table @option
 +@item x
 +@item y
 +the computed values for @var{x} and @var{y}. They are evaluated for
 +each new frame.
 +
 +@item in_w
 +@item in_h
 +the input width and height
 +
 +@item iw
 +@item ih
 +same as @var{in_w} and @var{in_h}
 +
 +@item out_w
 +@item out_h
 +the output (cropped) width and height
 +
 +@item ow
 +@item oh
 +same as @var{out_w} and @var{out_h}
 +
 +@item a
 +same as @var{iw} / @var{ih}
 +
 +@item sar
 +input sample aspect ratio
 +
 +@item dar
 +input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
 +
 +@item hsub
 +@item vsub
 +horizontal and vertical chroma subsample values. For example for the
 +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 +
 +@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 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 expression for @var{x} may depend on @var{y}, and the expression
 +for @var{y} may depend on @var{x}.
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Crop area with size 100x100 at position (12,34).
 +@example
 +crop=100:100:12:34
 +@end example
 +
 +Using named options, the example above becomes:
 +@example
 +crop=w=100:h=100:x=12:y=34
 +@end example
 +
 +@item
 +Crop the central input area with size 100x100:
 +@example
 +crop=100:100
 +@end example
 +
 +@item
 +Crop the central input area with size 2/3 of the input video:
 +@example
 +crop=2/3*in_w:2/3*in_h
 +@end example
 +
 +@item
 +Crop the input video central square:
 +@example
 +crop=out_w=in_h
 +crop=in_h
 +@end example
 +
 +@item
 +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:
 +@example
 +crop=in_w-100:in_h-100:100:100
 +@end example
 +
 +@item
 +Crop 10 pixels from the left and right borders, and 20 pixels from
 +the top and bottom borders
 +@example
 +crop=in_w-2*10:in_h-2*20
 +@end example
 +
 +@item
 +Keep only the bottom right quarter of the input image:
 +@example
 +crop=in_w/2:in_h/2:in_w/2:in_h/2
 +@end example
 +
 +@item
 +Crop height for getting Greek harmony:
 +@example
 +crop=in_w:1/PHI*in_w
 +@end example
 +
 +@item
 +Appply trembling effect:
 +@example
 +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)
 +@end example
 +
 +@item
 +Apply erratic camera effect depending on timestamp:
 +@example
 +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)"
 +@end example
 +
 +@item
 +Set x depending on the value of y:
 +@example
 +crop=in_w/2:in_h/2:y:10+10*sin(n/10)
 +@end example
 +@end itemize
 +
 +@section cropdetect
 +
 +Auto-detect crop size.
 +
 +Calculate necessary cropping parameters and prints the recommended
 +parameters through the logging system. The detected dimensions
 +correspond to the non-black area of the input video.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +
 +@item limit
 +Set higher black value threshold, which can be optionally specified
 +from nothing (0) to everything (255). An intensity value greater
 +to the set value is considered non-black. Default value is 24.
 +
 +@item round
 +Set the value for which the width/height should be divisible by. The
 +offset is automatically adjusted to center the video. Use 2 to get
 +only even dimensions (needed for 4:2:2 video). 16 is best when
 +encoding to most video codecs. Default value is 16.
 +
 +@item reset_count, reset
 +Set the counter that determines after how many frames cropdetect will
 +reset the previously detected largest video area and start over to
 +detect the current optimal crop area. Default value is 0.
 +
 +This can be useful when channel logos distort the video area. 0
 +indicates never reset and return the largest area encountered during
 +playback.
 +@end table
 +
 +@anchor{curves}
 +@section curves
 +
 +Apply color adjustments using curves.
 +
 +This filter is similar to the Adobe Photoshop and GIMP curves tools. Each
 +component (red, green and blue) has its values defined by @var{N} key points
 +tied from each other using a smooth curve. The x-axis represents the pixel
 +values from the input frame, and the y-axis the new pixel values to be set for
 +the output frame.
 +
 +By default, a component curve is defined by the two points @var{(0;0)} and
 +@var{(1;1)}. This creates a straight line where each original pixel value is
 +"adjusted" to its own value, which means no change to the image.
 +
 +The filter allows you to redefine these two points and add some more. A new
 +curve (using a natural cubic spline interpolation) will be define to pass
 +smoothly through all these new coordinates. The new defined points needs to be
 +strictly increasing over the x-axis, and their @var{x} and @var{y} values must
 +be in the @var{[0;1]} interval.  If the computed curves happened to go outside
 +the vector spaces, the values will be clipped accordingly.
 +
 +If there is no key point defined in @code{x=0}, the filter will automatically
 +insert a @var{(0;0)} point. In the same way, if there is no key point defined
 +in @code{x=1}, the filter will automatically insert a @var{(1;1)} point.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item preset
 +Select one of the available color presets. This option can be used in addition
 +to the @option{r}, @option{g}, @option{b} parameters; in this case, the later
 +options takes priority on the preset values.
 +Available presets are:
 +@table @samp
 +@item none
 +@item color_negative
 +@item cross_process
 +@item darker
 +@item increase_contrast
 +@item lighter
 +@item linear_contrast
 +@item medium_contrast
 +@item negative
 +@item strong_contrast
 +@item vintage
 +@end table
 +Default is @code{none}.
 +@item master, m
 +Set the master key points. These points will define a second pass mapping. It
 +is sometimes called a "luminance" or "value" mapping. It can be used with
 +@option{r}, @option{g}, @option{b} or @option{all} since it acts like a
 +post-processing LUT.
 +@item red, r
 +Set the key points for the red component.
 +@item green, g
 +Set the key points for the green component.
 +@item blue, b
 +Set the key points for the blue component.
 +@item all
 +Set the key points for all components (not including master).
 +Can be used in addition to the other key points component
 +options. In this case, the unset component(s) will fallback on this
 +@option{all} setting.
 +@item psfile
 +Specify a Photoshop curves file (@code{.asv}) to import the settings from.
 +@end table
 +
 +To avoid some filtergraph syntax conflicts, each key points list need to be
 +defined using the following syntax: @code{x0/y0 x1/y1 x2/y2 ...}.
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Increase slightly the middle level of blue:
 +@example
 +curves=blue='0.5/0.58'
 +@end example
 +
 +@item
 +Vintage effect:
 +@example
 +curves=r='0/0.11 .42/.51 1/0.95':g='0.50/0.48':b='0/0.22 .49/.44 1/0.8'
 +@end example
 +Here we obtain the following coordinates for each components:
 +@table @var
 +@item red
 +@code{(0;0.11) (0.42;0.51) (1;0.95)}
 +@item green
 +@code{(0;0) (0.50;0.48) (1;1)}
 +@item blue
 +@code{(0;0.22) (0.49;0.44) (1;0.80)}
 +@end table
 +
 +@item
 +The previous example can also be achieved with the associated built-in preset:
 +@example
 +curves=preset=vintage
 +@end example
 +
 +@item
 +Or simply:
 +@example
 +curves=vintage
 +@end example
 +
 +@item
 +Use a Photoshop preset and redefine the points of the green component:
 +@example
 +curves=psfile='MyCurvesPresets/purple.asv':green='0.45/0.53'
 +@end example
 +@end itemize
 +
 +@section dctdnoiz
 +
 +Denoise frames using 2D DCT (frequency domain filtering).
 +
 +This filter is not designed for real time and can be extremely slow.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item sigma, s
 +Set the noise sigma constant.
 +
 +This @var{sigma} defines a hard threshold of @code{3 * sigma}; every DCT
 +coefficient (absolute value) below this threshold with be dropped.
 +
 +If you need a more advanced filtering, see @option{expr}.
 +
 +Default is @code{0}.
 +
 +@item overlap
 +Set number overlapping pixels for each block. Each block is of size
 +@code{16x16}. Since the filter can be slow, you may want to reduce this value,
 +at the cost of a less effective filter and the risk of various artefacts.
 +
 +If the overlapping value doesn't allow to process the whole input width or
 +height, a warning will be displayed and according borders won't be denoised.
 +
 +Default value is @code{15}.
 +
 +@item expr, e
 +Set the coefficient factor expression.
 +
 +For each coefficient of a DCT block, this expression will be evaluated as a
 +multiplier value for the coefficient.
 +
 +If this is option is set, the @option{sigma} option will be ignored.
 +
 +The absolute value of the coefficient can be accessed through the @var{c}
 +variable.
 +@end table
 +
 +@subsection Examples
 +
 +Apply a denoise with a @option{sigma} of @code{4.5}:
 +@example
 +dctdnoiz=4.5
 +@end example
 +
 +The same operation can be achieved using the expression system:
 +@example
 +dctdnoiz=e='gte(c, 4.5*3)'
 +@end example
 +
 +@anchor{decimate}
 +@section decimate
 +
 +Drop duplicated frames at regular intervals.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item cycle
 +Set the number of frames from which one will be dropped. Setting this to
 +@var{N} means one frame in every batch of @var{N} frames will be dropped.
 +Default is @code{5}.
 +
 +@item dupthresh
 +Set the threshold for duplicate detection. If the difference metric for a frame
 +is less than or equal to this value, then it is declared as duplicate. Default
 +is @code{1.1}
 +
 +@item scthresh
 +Set scene change threshold. Default is @code{15}.
 +
 +@item blockx
 +@item blocky
 +Set the size of the x and y-axis blocks used during metric calculations.
 +Larger blocks give better noise suppression, but also give worse detection of
 +small movements. Must be a power of two. Default is @code{32}.
 +
 +@item ppsrc
 +Mark main input as a pre-processed input and activate clean source input
 +stream. This allows the input to be pre-processed with various filters to help
 +the metrics calculation while keeping the frame selection lossless. When set to
 +@code{1}, the first stream is for the pre-processed input, and the second
 +stream is the clean source from where the kept frames are chosen. Default is
 +@code{0}.
 +
 +@item chroma
 +Set whether or not chroma is considered in the metric calculations. Default is
 +@code{1}.
 +@end table
 +
 +@section delogo
 +
 +Suppress a TV station logo by a simple interpolation of the surrounding
 +pixels. Just set a rectangle covering the logo and watch it disappear
 +(and sometimes something even uglier appear - your mileage may vary).
 +
 +This filter accepts the following options:
 +@table @option
 +
 +@item x
 +@item y
 +Specify the top left corner coordinates of the logo. They must be
 +specified.
 +
 +@item w
 +@item h
 +Specify the width and height of the logo to clear. They must be
 +specified.
 +
 +@item band, t
 +Specify the thickness of the fuzzy edge of the rectangle (added to
 +@var{w} and @var{h}). The default value is 4.
 +
 +@item show
 +When set to 1, a green rectangle is drawn on the screen to simplify
 +finding the right @var{x}, @var{y}, @var{w}, and @var{h} parameters.
 +The default value is 0.
 +
 +The rectangle is drawn on the outermost pixels which will be (partly)
 +replaced with interpolated values. The values of the next pixels
 +immediately outside this rectangle in each direction will be used to
 +compute the interpolated pixel values inside the rectangle.
 +
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Set a rectangle covering the area with top left corner coordinates 0,0
 +and size 100x77, setting a band of size 10:
 +@example
 +delogo=x=0:y=0:w=100:h=77:band=10
 +@end example
 +
 +@end itemize
 +
 +@section deshake
 +
 +Attempt to fix small changes in horizontal and/or vertical shift. This
 +filter helps remove camera shake from hand-holding a camera, bumping a
 +tripod, moving on a vehicle, etc.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +
 +@item x
 +@item y
 +@item w
 +@item h
 +Specify a rectangular area where to limit the search for motion
 +vectors.
 +If desired the search for motion vectors can be limited to a
 +rectangular area of the frame defined by its top left corner, width
 +and height. These parameters have the same meaning as the drawbox
 +filter which can be used to visualise the position of the bounding
 +box.
 +
 +This is useful when simultaneous movement of subjects within the frame
 +might be confused for camera motion by the motion vector search.
 +
 +If any or all of @var{x}, @var{y}, @var{w} and @var{h} are set to -1
 +then the full frame is used. This allows later options to be set
 +without specifying the bounding box for the motion vector search.
 +
 +Default - search the whole frame.
 +
 +@item rx
 +@item ry
 +Specify the maximum extent of movement in x and y directions in the
 +range 0-64 pixels. Default 16.
 +
 +@item edge
 +Specify how to generate pixels to fill blanks at the edge of the
 +frame. Available values are:
 +@table @samp
 +@item blank, 0
 +Fill zeroes at blank locations
 +@item original, 1
 +Original image at blank locations
 +@item clamp, 2
 +Extruded edge value at blank locations
 +@item mirror, 3
 +Mirrored edge at blank locations
 +@end table
 +Default value is @samp{mirror}.
 +
 +@item blocksize
 +Specify the blocksize to use for motion search. Range 4-128 pixels,
 +default 8.
 +
 +@item contrast
 +Specify the contrast threshold for blocks. Only blocks with more than
 +the specified contrast (difference between darkest and lightest
 +pixels) will be considered. Range 1-255, default 125.
 +
 +@item search
 +Specify the search strategy. Available values are:
 +@table @samp
 +@item exhaustive, 0
 +Set exhaustive search
 +@item less, 1
 +Set less exhaustive search.
 +@end table
 +Default value is @samp{exhaustive}.
 +
 +@item filename
 +If set then a detailed log of the motion search is written to the
 +specified file.
 +
 +@item opencl
 +If set to 1, specify using OpenCL capabilities, only available if
 +FFmpeg was configured with @code{--enable-opencl}. Default value is 0.
 +
 +@end table
 +
 +@section drawbox
 +
 +Draw a colored box on the input image.
 +
 +This filter accepts the following options:
 +
 +@table @option
 +@item x
 +@item y
 +The expressions which specify the top left corner coordinates of the box. Default to 0.
 +
 +@item width, w
 +@item height, h
 +The expressions which specify the width and height of the box, if 0 they are interpreted as
 +the input width and height. Default to 0.
 +
 +@item color, c
 +Specify the color of the box to write, it can be the name of a color
 +(case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
 +value @code{invert} is used, the box edge color is the same as the
 +video with inverted luma.
 +
 +@item thickness, t
 +The expression which sets the thickness of the box edge. Default value is @code{3}.
 +
 +See below for the list of accepted constants.
 +@end table
 +
 +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
 +following constants:
 +
 +@table @option
 +@item dar
 +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
 +
 +@item hsub
 +@item vsub
 +horizontal and vertical chroma subsample values. For example for the
 +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 +
 +@item in_h, ih
 +@item in_w, iw
 +The input width and height.
 +
 +@item sar
 +The input sample aspect ratio.
 +
 +@item x
 +@item y
 +The x and y offset coordinates where the box is drawn.
 +
 +@item w
 +@item h
 +The width and height of the drawn box.
 +
 +@item t
 +The thickness of the drawn box.
 +
 +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
 +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
 +
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Draw a black box around the edge of the input image:
 +@example
 +drawbox
 +@end example
 +
 +@item
 +Draw a box with color red and an opacity of 50%:
 +@example
 +drawbox=10:20:200:60:red@@0.5
 +@end example
 +
 +The previous example can be specified as:
 +@example
 +drawbox=x=10:y=20:w=200:h=60:color=red@@0.5
 +@end example
 +
 +@item
 +Fill the box with pink color:
 +@example
 +drawbox=x=10:y=10:w=100:h=100:color=pink@@0.5:t=max
 +@end example
 +
 +@item
 +Draw a 2-pixel red 2.40:1 mask:
 +@example
 +drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red
 +@end example
 +@end itemize
 +
 +@section drawgrid
 +
 +Draw a grid on the input image.
 +
 +This filter accepts the following options:
 +
 +@table @option
 +@item x
 +@item y
 +The expressions which specify the coordinates of some point of grid intersection (meant to configure offset). Both default to 0.
 +
 +@item width, w
 +@item height, h
 +The expressions which specify the width and height of the grid cell, if 0 they are interpreted as the
 +input width and height, respectively, minus @code{thickness}, so image gets
 +framed. Default to 0.
 +
 +@item color, c
 +Specify the color of the grid, it can be the name of a color
 +(case insensitive match) or a 0xRRGGBB[AA] sequence. If the special
 +value @code{invert} is used, the grid color is the same as the
 +video with inverted luma.
 +Note that you can append opacity value (in range of 0.0 - 1.0)
 +to color name after @@ sign.
 +
 +@item thickness, t
 +The expression which sets the thickness of the grid line. Default value is @code{1}.
 +
 +See below for the list of accepted constants.
 +@end table
 +
 +The parameters for @var{x}, @var{y}, @var{w} and @var{h} and @var{t} are expressions containing the
 +following constants:
 +
 +@table @option
 +@item dar
 +The input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}.
 +
 +@item hsub
 +@item vsub
 +horizontal and vertical chroma subsample values. For example for the
 +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 +
 +@item in_h, ih
 +@item in_w, iw
 +The input grid cell width and height.
 +
 +@item sar
 +The input sample aspect ratio.
 +
 +@item x
 +@item y
 +The x and y coordinates of some point of grid intersection (meant to configure offset).
 +
 +@item w
 +@item h
 +The width and height of the drawn cell.
 +
 +@item t
 +The thickness of the drawn cell.
 +
 +These constants allow the @var{x}, @var{y}, @var{w}, @var{h} and @var{t} expressions to refer to
 +each other, so you may for example specify @code{y=x/dar} or @code{h=w/dar}.
 +
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Draw a grid with cell 100x100 pixels, thickness 2 pixels, with color red and an opacity of 50%:
 +@example
 +drawgrid=width=100:height=100:thickness=2:color=red@@0.5
 +@end example
 +
 +@item
 +Draw a white 3x3 grid with an opacity of 50%:
 +@example
 +drawgrid=w=iw/3:h=ih/3:t=2:c=white@@0.5
 +@end example
 +@end itemize
 +
 +@anchor{drawtext}
 +@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}.
 +
 +@subsection Syntax
 +
 +The description of the accepted parameters follows.
 +
 +@table @option
 +
 +@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 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 draw
 +Set an expression which specifies if the text should be drawn. If the
 +expression evaluates to 0, the text is not drawn. This is useful for
 +specifying that the text should be drawn only when specific conditions
 +are met.
 +
 +Default value is "1".
 +
 +See below for the list of accepted constants and functions.
 +
 +@item expansion
 +Select how the @var{text} is expanded. Can be either @code{none},
 +@code{strftime} (deprecated) or
 +@code{normal} (default). See the @ref{drawtext_expansion, Text expansion} section
 +below for details.
 +
 +@item fix_bounds
 +If true, check and fix text coords to avoid clipping.
 +
 +@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 fontfile
 +The font file to be used for drawing text. Path must be included.
 +This parameter is mandatory.
 +
 +@item fontsize
 +The font size to be used for drawing text.
 +The default value of @var{fontsize} is 16.
 +
 +@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
 +@end table
 +
 +Default value is "render".
 +
 +For more information consult the documentation for the FT_LOAD_*
 +libfreetype flags.
 +
 +@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 shadowx
 +@item 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 start_number
 +The starting frame number for the n/frame_num variable. The default value
 +is "0".
 +
 +@item tabsize
 +The size in number of spaces to use for rendering the tab.
 +Default value is 4.
 +
 +@item timecode
 +Set the initial timecode representation in "hh:mm:ss[:;.]ff"
 +format. It can be used with or without text parameter. @var{timecode_rate}
 +option must be specified.
 +
 +@item timecode_rate, rate, r
 +Set the timecode frame rate (timecode only).
 +
 +@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 @var{text} and @var{textfile} are specified, an error is thrown.
 +
 +@item reload
 +If set to 1, the @var{textfile} will be reloaded before each frame.
 +Be sure to update it atomically, or it may be read partially, or even fail.
 +
 +@item x
 +@item y
 +The expressions which specify the offsets where text will be drawn
 +within the video frame. They are relative to the top/left border of the
 +output image.
 +
 +The default value of @var{x} and @var{y} is "0".
 +
 +See below for the list of accepted constants and functions.
 +@end table
 +
 +The parameters for @var{x} and @var{y} are expressions containing the
 +following constants and functions:
 +
 +@table @option
 +@item dar
 +input display aspect ratio, it is the same as (@var{w} / @var{h}) * @var{sar}
 +
 +@item hsub
 +@item vsub
 +horizontal and vertical chroma subsample values. For example for the
 +pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 +
 +@item line_h, lh
 +the height of each text line
 +
 +@item main_h, h, H
 +the input height
 +
 +@item main_w, w, W
 +the input width
 +
 +@item max_glyph_a, ascent
 +the maximum distance from the baseline to the highest/upper grid
 +coordinate used to place a glyph outline point, for all the rendered
 +glyphs.
 +It is a positive value, due to the grid's orientation with the Y axis
 +upwards.
 +
 +@item max_glyph_d, descent
 +the maximum distance from the baseline to the lowest grid coordinate
 +used to place a glyph outline point, for all the rendered glyphs.
 +This is a negative value, due to the grid's orientation, with the Y axis
 +upwards.
 +
 +@item max_glyph_h
 +maximum glyph height, that is the maximum height for all the glyphs
 +contained in the rendered text, it is equivalent to @var{ascent} -
 +@var{descent}.
 +
 +@item max_glyph_w
 +maximum glyph width, that is the maximum width for all the glyphs
 +contained in the rendered text
 +
 +@item n
 +the number of input frame, starting from 0
 +
 +@item rand(min, max)
 +return a random number included between @var{min} and @var{max}
 +
 +@item sar
 +input sample aspect ratio
 +
 +@item t
 +timestamp expressed in seconds, NAN if the input timestamp is unknown
 +
 +@item text_h, th
 +the height of the rendered text
 +
 +@item text_w, tw
 +the width of the rendered text
 +
 +@item x
 +@item y
 +the x and y offset coordinates where the text is drawn.
 +
 +These parameters allow the @var{x} and @var{y} expressions to refer
 +each other, so you can for example specify @code{y=x/dar}.
 +@end table
 +
 +If libavfilter was built with @code{--enable-fontconfig}, then
 +@option{fontfile} can be a fontconfig pattern or omitted.
 +
 +@anchor{drawtext_expansion}
 +@subsection Text expansion
 +
 +If @option{expansion} is set to @code{strftime},
 +the filter recognizes strftime() sequences in the provided text and
 +expands them accordingly. Check the documentation of strftime(). This
 +feature is deprecated.
 +
 +If @option{expansion} is set to @code{none}, the text is printed verbatim.
 +
 +If @option{expansion} is set to @code{normal} (which is the default),
 +the following expansion mechanism is used.
 +
 +The backslash character '\', followed by any character, always expands to
 +the second character.
 +
 +Sequence of the form @code{%@{...@}} are expanded. The text between the
 +braces is a function name, possibly followed by arguments separated by ':'.
 +If the arguments contain special characters or delimiters (':' or '@}'),
 +they should be escaped.
 +
 +Note that they probably must also be escaped as the value for the
 +@option{text} option in the filter argument string and as the filter
 +argument in the filtergraph description, and possibly also for the shell,
 +that makes up to four levels of escaping; using a text file avoids these
 +problems.
 +
 +The following functions are available:
 +
 +@table @command
 +
 +@item expr, e
 +The expression evaluation result.
 +
 +It must take one argument specifying the expression to be evaluated,
 +which accepts the same constants and functions as the @var{x} and
 +@var{y} values. Note that not all constants should be used, for
 +example the text size is not known when evaluating the expression, so
 +the constants @var{text_w} and @var{text_h} will have an undefined
 +value.
 +
 +@item gmtime
 +The time at which the filter is running, expressed in UTC.
 +It can accept an argument: a strftime() format string.
 +
 +@item localtime
 +The time at which the filter is running, expressed in the local time zone.
 +It can accept an argument: a strftime() format string.
 +
 +@item metadata
 +Frame metadata. It must take one argument specifying metadata key.
 +
 +@item n, frame_num
 +The frame number, starting from 0.
 +
 +@item pict_type
 +A 1 character description of the current picture type.
 +
 +@item pts
 +The timestamp of the current frame, in seconds, with microsecond accuracy.
 +
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Draw "Test Text" with font FreeSerif, using the default values for the
 +optional parameters.
 +
 +@example
 +drawtext="fontfile=/usr/share/fonts/truetype/freefont/FreeSerif.ttf: text='Test Text'"
 +@end example
 +
 +@item
 +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%.
 +
 +@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
 +
 +Note that the double quotes are not necessary if spaces are not used
 +within the parameter list.
 +
 +@item
 +Show the text at the center of the video frame:
 +@example
 +drawtext="fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h-line_h)/2"
 +@end example
 +
 +@item
 +Show a text line sliding from right to left in the last row of the video
 +frame. The file @file{LONG_LINE} is assumed to contain a single line
 +with no newlines.
 +@example
 +drawtext="fontsize=15:fontfile=FreeSerif.ttf:text=LONG_LINE:y=h-line_h:x=-50*t"
 +@end example
 +
 +@item
 +Show the content of file @file{CREDITS} off the bottom of the frame and scroll up.
 +@example
 +drawtext="fontsize=20:fontfile=FreeSerif.ttf:textfile=CREDITS:y=h-20*t"
 +@end example
 +
 +@item
 +Draw a single green letter "g", at the center of the input video.
 +The glyph baseline is placed at half screen height.
 +@example
 +drawtext="fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent"
 +@end example
 +
 +@item
 +Show text for 1 second every 3 seconds:
 +@example
 +drawtext="fontfile=FreeSerif.ttf:fontcolor=white:x=100:y=x/dar:draw=lt(mod(t\,3)\,1):text='blink'"
 +@end example
 +
 +@item
 +Use fontconfig to set the font. Note that the colons need to be escaped.
 +@example
 +drawtext='fontfile=Linux Libertine O-40\:style=Semibold:text=FFmpeg'
 +@end example
 +
 +@item
 +Print the date of a real-time encoding (see strftime(3)):
 +@example
 +drawtext='fontfile=FreeSans.ttf:text=%@{localtime:%a %b %d %Y@}'
 +@end example
 +
 +@end itemize
 +
 +For more information about libfreetype, check:
 +@url{http://www.freetype.org/}.
 +
 +For more information about fontconfig, check:
 +@url{http://freedesktop.org/software/fontconfig/fontconfig-user.html}.
 +
 +@section edgedetect
 +
 +Detect and draw edges. The filter uses the Canny Edge Detection algorithm.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item low
 +@item high
 +Set low and high threshold values used by the Canny thresholding
 +algorithm.
 +
 +The high threshold selects the "strong" edge pixels, which are then
 +connected through 8-connectivity with the "weak" edge pixels selected
 +by the low threshold.
 +
 +@var{low} and @var{high} threshold values must be choosen in the range
 +[0,1], and @var{low} should be lesser or equal to @var{high}.
 +
 +Default value for @var{low} is @code{20/255}, and default value for @var{high}
 +is @code{50/255}.
 +@end table
 +
 +Example:
 +@example
 +edgedetect=low=0.1:high=0.4
 +@end example
 +
 +@section extractplanes
 +
 +Extract color channel components from input video stream into
 +separate grayscale video streams.
 +
 +The filter accepts the following option:
 +
 +@table @option
 +@item planes
 +Set plane(s) to extract.
 +
 +Available values for planes are:
 +@table @samp
 +@item y
 +@item u
 +@item v
 +@item a
 +@item r
 +@item g
 +@item b
 +@end table
 +
 +Choosing planes not available in the input will result in an error.
 +That means you cannot select @code{r}, @code{g}, @code{b} planes
 +with @code{y}, @code{u}, @code{v} planes at same time.
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Extract luma, u and v color channel component from input video frame
 +into 3 grayscale outputs:
 +@example
 +ffmpeg -i video.avi -filter_complex 'extractplanes=y+u+v[y][u][v]' -map '[y]' y.avi -map '[u]' u.avi -map '[v]' v.avi
 +@end example
 +@end itemize
 +
 +@section fade
 +
 +Apply fade-in/out effect to input video.
 +
 +This filter accepts the following options:
 +
 +@table @option
 +@item type, t
 +The effect type -- can be either "in" for fade-in, or "out" for a fade-out
 +effect.
 +Default is @code{in}.
 +
 +@item start_frame, s
 +Specify the number of the start frame for starting to apply the fade
 +effect. Default is 0.
 +
 +@item nb_frames, n
 +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.
 +Default is 25.
 +
 +@item alpha
 +If set to 1, fade only alpha channel, if one exists on the input.
 +Default value is 0.
 +
 +@item start_time, st
 +Specify the timestamp (in seconds) of the frame to start to apply the fade
 +effect. If both start_frame and start_time are specified, the fade will start at
 +whichever comes last.  Default is 0.
 +
 +@item duration, d
 +The number of seconds 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.
 +If both duration and nb_frames are specified, duration is used. Default is 0.
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Fade in first 30 frames of video:
 +@example
 +fade=in:0:30
 +@end example
 +
 +The command above is equivalent to:
 +@example
 +fade=t=in:s=0:n=30
 +@end example
 +
 +@item
 +Fade out last 45 frames of a 200-frame video:
 +@example
 +fade=out:155:45
 +fade=type=out:start_frame=155:nb_frames=45
 +@end example
 +
 +@item
 +Fade in first 25 frames and fade out last 25 frames of a 1000-frame video:
 +@example
 +fade=in:0:25, fade=out:975:25
 +@end example
 +
 +@item
 +Make first 5 frames black, then fade in from frame 5-24:
 +@example
 +fade=in:5:20
 +@end example
 +
 +@item
 +Fade in alpha over first 25 frames of video:
 +@example
 +fade=in:0:25:alpha=1
 +@end example
 +
 +@item
 +Make first 5.5 seconds black, then fade in for 0.5 seconds:
 +@example
 +fade=t=in:st=5.5:d=0.5
 +@end example
 +
 +@end itemize
 +
 +@section field
 +
 +Extract a single field from an interlaced image using stride
 +arithmetic to avoid wasting CPU time. The output frames are marked as
 +non-interlaced.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item type
 +Specify whether to extract the top (if the value is @code{0} or
 +@code{top}) or the bottom field (if the value is @code{1} or
 +@code{bottom}).
 +@end table
 +
 +@section fieldmatch
 +
 +Field matching filter for inverse telecine. It is meant to reconstruct the
 +progressive frames from a telecined stream. The filter does not drop duplicated
 +frames, so to achieve a complete inverse telecine @code{fieldmatch} needs to be
 +followed by a decimation filter such as @ref{decimate} in the filtergraph.
 +
 +The separation of the field matching and the decimation is notably motivated by
 +the possibility of inserting a de-interlacing filter fallback between the two.
 +If the source has mixed telecined and real interlaced content,
 +@code{fieldmatch} will not be able to match fields for the interlaced parts.
 +But these remaining combed frames will be marked as interlaced, and thus can be
 +de-interlaced by a later filter such as @ref{yadif} before decimation.
 +
 +In addition to the various configuration options, @code{fieldmatch} can take an
 +optional second stream, activated through the @option{ppsrc} option. If
 +enabled, the frames reconstruction will be based on the fields and frames from
 +this second stream. This allows the first input to be pre-processed in order to
 +help the various algorithms of the filter, while keeping the output lossless
 +(assuming the fields are matched properly). Typically, a field-aware denoiser,
 +or brightness/contrast adjustments can help.
 +
 +Note that this filter uses the same algorithms as TIVTC/TFM (AviSynth project)
 +and VIVTC/VFM (VapourSynth project). The later is a light clone of TFM from
 +which @code{fieldmatch} is based on. While the semantic and usage are very
 +close, some behaviour and options names can differ.
 +
 +The filter accepts the following options:
 +
 +@table @option
 +@item order
 +Specify the assumed field order of the input stream. Available values are:
 +
 +@table @samp
 +@item auto
 +Auto detect parity (use FFmpeg's internal parity value).
 +@item bff
 +Assume bottom field first.
 +@item tff
 +Assume top field first.
 +@end table
 +
 +Note that it is sometimes recommended not to trust the parity announced by the
 +stream.
 +
 +Default value is @var{auto}.
 +
 +@item mode
 +Set the matching mode or strategy to use. @option{pc} mode is the safest in the
 +sense that it won't risk creating jerkiness due to duplicate frames when
 +possible, but if there are bad edits or blended fields it will end up
 +outputting combed frames when a good match might actually exist. On the other
 +hand, @option{pcn_ub} mode is the most risky in terms of creating jerkiness,
 +but will almost always find a good frame if there is one. The other values are
 +all somewhere in between @option{pc} and @option{pcn_ub} in terms of risking
 +jerkiness and creating duplicate frames versus finding good matches in sections
 +with bad edits, orphaned fields, blended fields, etc.
 +
 +More details about p/c/n/u/b are available in @ref{p/c/n/u/b meaning} section.
 +
 +Available values are:
 +
 +@table @samp
 +@item pc
 +2-way matching (p/c)
 +@item pc_n
 +2-way matching, and trying 3rd match if still combed (p/c + n)
 +@item pc_u
 +2-way matching, and trying 3rd match (same order) if still combed (p/c + u)
 +@item pc_n_ub
 +2-way matching, trying 3rd match if still combed, and trying 4th/5th matches if
 +still combed (p/c + n + u/b)
 +@item pcn
 +3-way matching (p/c/n)
 +@item pcn_ub
 +3-way matching, and trying 4th/5th matches if all 3 of the original matches are
 +detected as combed (p/c/n + u/b)
 +@end table
 +
 +The parenthesis at the end indicate the matches that would be used for that
 +mode assuming @option{order}=@var{tff} (and @option{field} on @var{auto} or
 +@var{top}).
 +
 +In terms of speed @option{pc} mode is by far the fastest and @option{pcn_ub} is
 +the slowest.
 +
 +Default value is @var{pc_n}.
 +
 +@item ppsrc
 +Mark the main input stream as a pre-processed input, and enable the secondary
 +input stream as the clean source to pick the fields from. See the filter
 +introduction for more details. It is similar to the @option{clip2} feature from
 +VFM/TFM.
 +
 +Default value is @code{0} (disabled).
 +
 +@item field
 +Set the field to match from. It is recommended to set this to the same value as
 +@option{order} unless you experience matching failures with that setting. In
 +certain circumstances changing the field that is used to match from can have a
 +large impact on matching performance. Available values are:
 +
 +@table @samp
 +@item auto
 +Automatic (same value as @option{order}).
 +@item bottom
 +Match from the bottom field.
 +@item top
 +Match from the top field.
 +@end table
 +
 +Default value is @var{auto}.
 +
 +@item mchroma
 +Set whether or not chroma is included during the match comparisons. In most
 +cases it is recommended to leave this enabled. You should set this to @code{0}
 +only if your clip has bad chroma problems such as heavy rainbowing or other
 +artifacts. Setting this to @code{0} could also be used to speed things up at
 +the cost of some accuracy.
 +
 +Default value is @code{1}.
 +
 +@item y0
 +@item y1
 +These define an exclusion band which excludes the lines between @option{y0} and
 +@option{y1} from being included in the field matching decision. An exclusion
 +band can be used to ignore subtitles, a logo, or other things that may
 +interfere with the matching. @option{y0} sets the starting scan line and
 +@option{y1} sets the ending line; all lines in between @option{y0} and
 +@option{y1} (including @option{y0} and @option{y1}) will be ignored. Setting
 +@option{y0} and @option{y1} to the same value will disable the feature.
 +@option{y0} and @option{y1} defaults to @code{0}.
 +
 +@item scthresh
 +Set the scene change detection threshold as a percentage of maximum change on
 +the luma plane. Good values are in the @code{[8.0, 14.0]} range. Scene change
 +detection is only relevant in case @option{combmatch}=@var{sc}.  The range for
 +@option{scthresh} is @code{[0.0, 100.0]}.
 +
 +Default value is @code{12.0}.
 +
 +@item combmatch
 +When @option{combatch} is not @var{none}, @code{fieldmatch} will take into
 +account the combed scores of matches when deciding what match to use as the
 +final match. Available values are:
 +
 +@table @samp
 +@item none
 +No final matching based on combed scores.
 +@item sc
 +Combed scores are only used when a scene change is detected.
 +@item full
 +Use combed scores all the time.
 +@end table
 +
 +Default is @var{sc}.
 +
 +@item combdbg
 +Force @code{fieldmatch} to calculate the combed metrics for certain matches and
 +print them. This setting is known as @option{micout} in TFM/VFM vocabulary.
 +Available values are:
 +
 +@table @samp
 +@item none
 +No forced calculation.
 +@item pcn
 +Force p/c/n calculations.
 +@item pcnub
 +Force p/c/n/u/b calculations.
 +@end table
 +
 +Default value is @var{none}.
 +
 +@item cthresh
 +This is the area combing threshold used for combed frame detection. This
 +essentially controls how "strong" or "visible" combing must be to be detected.
 +Larger values mean combing must be more visible and smaller values mean combing
 +can be less visible or strong and still be detected. Valid settings are from
 +@code{-1} (every pixel will be detected as combed) to @code{255} (no pixel will
 +be detected as combed). This is basically a pixel difference value. A good
 +range is @code{[8, 12]}.
 +
 +Default value is @code{9}.
 +
 +@item chroma
 +Sets whether or not chroma is considered in the combed frame decision.  Only
 +disable this if your source has chroma problems (rainbowing, etc.) that are
 +causing problems for the combed frame detection with chroma enabled. Actually,
 +using @option{chroma}=@var{0} is usually more reliable, except for the case
 +where there is chroma only combing in the source.
 +
 +Default value is @code{0}.
 +
 +@item blockx
 +@item blocky
 +Respectively set the x-axis and y-axis size of the window used during combed
 +frame detection. This has to do with the size of the area in which
 +@option{combpel} pixels are required to be detected as combed for a frame to be
 +declared combed. See the @option{combpel} parameter description for more info.
 +Possible values are any number that is a power of 2 starting at 4 and going up
 +to 512.
 +
 +Default value is @code{16}.
 +
 +@item combpel
 +The number of combed pixels inside any of the @option{blocky} by
 +@option{blockx} size blocks on the frame for the frame to be detected as
 +combed. While @option{cthresh} controls how "visible" the combing must be, this
 +setting controls "how much" combing there must be in any localized area (a
 +window defined by the @option{blockx} and @option{blocky} settings) on the
 +frame. Minimum value is @code{0} and maximum is @code{blocky x blockx} (at
 +which point no frames will ever be detected as combed). This setting is known
 +as @option{MI} in TFM/VFM vocabulary.
 +
 +Default value is @code{80}.
 +@end table
 +
 +@anchor{p/c/n/u/b meaning}
 +@subsection p/c/n/u/b meaning
 +
 +@subsubsection p/c/n
 +
 +We assume the following telecined stream:
 +
 +@example
 +Top fields:     1 2 2 3 4
 +Bottom fields:  1 2 3 4 4
 +@end example
 +
 +The numbers correspond to the progressive frame the fields relate to. Here, the
 +first two frames are progressive, the 3rd and 4th are combed, and so on.
 +
 +When @code{fieldmatch} is configured to run a matching from bottom
 +(@option{field}=@var{bottom}) this is how this input stream get transformed:
 +
 +@example
 +Input stream:
 +                T     1 2 2 3 4
 +                B     1 2 3 4 4   <-- matching reference
 +
 +Matches:              c c n n c
 +
 +Output stream:
 +                T     1 2 3 4 4
 +                B     1 2 3 4 4
 +@end example
 +
 +As a result of the field matching, we can see that some frames get duplicated.
 +To perform a complete inverse telecine, you need to rely on a decimation filter
 +after this operation. See for instance the @ref{decimate} filter.
 +
 +The same operation now matching from top fields (@option{field}=@var{top})
 +looks like this:
 +
 +@example
 +Input stream:
 +                T     1 2 2 3 4   <-- matching reference
 +                B     1 2 3 4 4
 +
 +Matches:              c c p p c
 +
 +Output stream:
 +                T     1 2 2 3 4
 +                B     1 2 2 3 4
 +@end example
 +
 +In these examples, we can see what @var{p}, @var{c} and @var{n} mean;
 +basically, they refer to the frame and field of the opposite parity:
 +
 +@itemize
 +@item @var{p} matches the field of the opposite parity in the previous frame
 +@item @var{c} matches the field of the opposite parity in the current frame
 +@item @var{n} matches the field of the opposite parity in the next frame
 +@end itemize
 +
 +@subsubsection u/b
 +
 +The @var{u} and @var{b} matching are a bit special in the sense that they match
 +from the opposite parity flag. In the following examples, we assume that we are
 +currently matching the 2nd frame (Top:2, bottom:2). According to the match, a
 +'x' is placed above and below each matched fields.
 +
 +With bottom matching (@option{field}=@var{bottom}):
 +@example
 +Match:           c         p           n          b          u
 +
 +                 x       x               x        x          x
 +  Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
 +  Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
 +                 x         x           x        x              x
 +
 +Output frames:
 +                 2          1          2          2          2
 +                 2          2          2          1          3
 +@end example
 +
 +With top matching (@option{field}=@var{top}):
 +@example
 +Match:           c         p           n          b          u
 +
 +                 x         x           x        x              x
 +  Top          1 2 2     1 2 2       1 2 2      1 2 2      1 2 2
 +  Bottom       1 2 3     1 2 3       1 2 3      1 2 3      1 2 3
 +                 x       x               x        x          x
 +
 +Output frames:
 +                 2          2          2          1          2
 +                 2          1          3          2          2
 +@end example
 +
 +@subsection Examples
 +
 +Simple IVTC of a top field first telecined stream:
 +@example
 +fieldmatch=order=tff:combmatch=none, decimate
 +@end example
 +
 +Advanced IVTC, with fallback on @ref{yadif} for still combed frames:
 +@example
 +fieldmatch=order=tff:combmatch=full, yadif=deint=interlaced, decimate
 +@end example
 +
 +@section fieldorder
 +
 +Transform the field order of the input video.
 +
 +This filter accepts the following options:
 +
 +@table @option
 +
 +@item order
 +Output field order. Valid values are @var{tff} for top field first or @var{bff}
 +for bottom field first.
 +@end table
 +
 +Default value is @samp{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.
 +
 +This filter is mainly useful when auto-inserted by the libavfilter
 +framework.
 +
 +The filter does not take parameters.
 +
 +@anchor{format}
 +@section format
 +
 +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.
 +
 +This filter accepts the following parameters:
 +@table @option
 +
 +@item pix_fmts
 +A '|'-separated list of pixel format names, for example
 +"pix_fmts=yuv420p|monow|rgb24".
 +
 +@end table
 +
 +@subsection Examples
 +
 +@itemize
 +@item
 +Convert the input video to the format @var{yuv420p}
 +@example
 +format=pix_fmts=yuv420p
 +@end example
 +
 +Convert the input video to any of the formats in the list
 +@example
 +format=pix_fmts=yuv420p|yuv444p|yuv410p
 +@end example
 +@end itemize
 +
 +@section fps
 +
 +Convert the video to specified constant frame rate by duplicating or dropping
 +frames as necessary.
 +
 +This filter accepts the following named parameters:
 +@table @option
 +
 +@item fps
 +Desired output frame rate. The default is @code{25}.
 +
 +@item round
 +Rounding method.
 +
 +Possible values are:
 +@table @option
 +@item zero
 +zero round towards 0
 +@item inf
 +round away from 0
 +@item down
 +round towards -infinity
 +@item up
 +round towards +infinity
 +@item near
 +round to nearest
 +@end table
 +The default is @code{near}.
 +
 +@end table
 +
 +Alternatively, the options can be specified as a flat string:
 +@var{fps}[:@var{round}].
 +
 +See also the @ref{setpts} filter.
 +
++@item start_time
++Assume the first PTS should be the given value, in seconds. This allows for
++padding/trimming at the start of stream. By default, no assumption is made
++about the first frame's expected PTS, so no padding or trimming is done.
++For example, this could be set to 0 to pad the beginning with duplicates of
++the first frame if a video stream starts after the audio stream or to trim any
++frames with a negative PTS.
++
 +@subsection Examples
 +
 +@itemize
 +@item
 +A typical usage in order to set the fps to 25:
 +@example
 +fps=fps=25
 +@end example
 +
 +@item
 +Sets the fps to 24, using abbreviation and rounding method to round to nearest:
 +@example
 +fps=fps=film:round=near
 +@end example
 +@end itemize
 +
 +@section framestep
 +
 +Select one frame every N-th frame.
 +
 +This filter accepts the following option:
 +@table @option
 +@item step
 +Select frame after every @code{step} frames.
 +Allowed values are positive integers higher than 0. Default value is @code{1}.
 +@end table
 +
 +@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 @code{--enable-frei0r}.
 +
 +This filter accepts the following options:
 +
 +@table @option
 +
 +@item filter_name
 +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/}.
 +
 +@item filter_params
 +A '|'-separated list of parameters to pass to the frei0r effect.
 +
 +@end table
 +
 +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.
@@@ -44,8 -40,10 +44,10 @@@ typedef struct FPSContext 
      int64_t first_pts;      ///< pts of the first frame that arrived on this filter
      int64_t pts;            ///< pts of the first frame currently in the fifo
  
+     double start_time;      ///< pts, in seconds, of the expected first frame
      AVRational framerate;   ///< target framerate
 -    char *fps;              ///< a string describing target framerate
 +    int rounding;           ///< AVRounding method for timestamps
  
      /* statistics */
      int frames_in;             ///< number of frames on input
  
  #define OFFSET(x) offsetof(FPSContext, x)
  #define V AV_OPT_FLAG_VIDEO_PARAM
 -static const AVOption options[] = {
 -    { "fps", "A string describing desired output framerate", OFFSET(fps), AV_OPT_TYPE_STRING, { .str = "25" }, .flags = V },
 +#define F AV_OPT_FLAG_FILTERING_PARAM
 +static const AVOption fps_options[] = {
 +    { "fps", "A string describing desired output framerate", OFFSET(framerate), AV_OPT_TYPE_VIDEO_RATE, { .str = "25" }, .flags = V|F },
+     { "start_time", "Assume the first PTS should be this value.", OFFSET(start_time), AV_OPT_TYPE_DOUBLE, { .dbl = AV_NOPTS_VALUE}, INT64_MIN, INT64_MAX, V },
 +    { "round", "set rounding method for timestamps", OFFSET(rounding), AV_OPT_TYPE_INT, { .i64 = AV_ROUND_NEAR_INF }, 0, 5, V|F, "round" },
 +    { "zero", "round towards 0",      OFFSET(rounding), AV_OPT_TYPE_CONST, { .i64 = AV_ROUND_ZERO     }, 0, 5, V|F, "round" },
 +    { "inf",  "round away from 0",    OFFSET(rounding), AV_OPT_TYPE_CONST, { .i64 = AV_ROUND_INF      }, 0, 5, V|F, "round" },
 +    { "down", "round towards -infty", OFFSET(rounding), AV_OPT_TYPE_CONST, { .i64 = AV_ROUND_DOWN     }, 0, 5, V|F, "round" },
 +    { "up",   "round towards +infty", OFFSET(rounding), AV_OPT_TYPE_CONST, { .i64 = AV_ROUND_UP       }, 0, 5, V|F, "round" },
 +    { "near", "round to nearest",     OFFSET(rounding), AV_OPT_TYPE_CONST, { .i64 = AV_ROUND_NEAR_INF }, 0, 5, V|F, "round" },
      { NULL },
  };