A filter with no input pads is called a "source", a filter with no
output pads is called a "sink".
+@anchor{Filtergraph syntax}
@section Filtergraph syntax
-A filtergraph can be represented using a textual representation, which
-is recognized by the @code{-vf} option of the ff*
-tools, and by the @code{avfilter_graph_parse()} function defined in
+A filtergraph can be represented using a textual representation, which is
+recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}
+options in @command{ffmpeg} and @option{-vf} in @command{ffplay}, and by the
+@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in
@file{libavfilter/avfiltergraph.h}.
A filterchain consists of a sequence of connected filters, each one
pads must be connected. A filtergraph is considered valid if all the
filter input and output pads of all the filterchains are connected.
+Libavfilter will automatically insert scale filters where format
+conversion is required. It is possible to specify swscale flags
+for those automatically inserted scalers by prepending
+@code{sws_flags=@var{flags};}
+to the filtergraph description.
+
Follows a BNF description for the filtergraph syntax:
@example
@var{NAME} ::= sequence of alphanumeric characters and '_'
@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
@var{FILTER} ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]
-@var{FILTERGRAPH} ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
+@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
@end example
@c man end FILTERGRAPH DESCRIPTION
@itemize
@item gain coefficients are zeroes or ones,
@item only one input per channel output,
-@item the number of output channels is supported by libswresample (16 at the
- moment)
-@c if SWR_CH_MAX changes, fix the line above.
@end itemize
If all these conditions are satisfied, the filter will notify the user ("Pure
will instruct the source to accept planar 16bit signed stereo at 44100Hz.
Since the sample format with name "s16" corresponds to the number
-1 and the "stereo" channel layout corresponds to the value 3, this is
+1 and the "stereo" channel layout corresponds to the value 0x3, this is
equivalent to:
@example
-abuffer=44100:1:3:1
+abuffer=44100:1:0x3:1
@end example
@section aevalsrc
To enable compilation of this filter you need to configure FFmpeg with
@code{--enable-libass}.
-This filter accepts in input the name of the ass file to render.
+This filter accepts the syntax: @var{ass_filename}[:@var{options}],
+where @var{ass_filename} is the filename of the ASS file to read, and
+@var{options} is an optional sequence of @var{key}=@var{value} pairs,
+separated by ":".
+
+A description of the accepted options follows.
+
+@table @option
+@item original_size
+Specifies the size of the original video, the video for which the ASS file
+was composed. Due to a misdesign in ASS aspect ratio arithmetic, this is
+necessary to correctly scale the fonts if the aspect ratio has been changed.
+@end table
For example, to render the file @file{sub.ass} on top of the input
video, use the command:
ass=sub.ass
@end example
+@section bbox
+
+Compute the bounding box for the non-black pixels in the input frame
+luminance plane.
+
+This filter computes the bounding box containing all the pixels with a
+luminance value greater than the minimum allowed value.
+The parameters describing the bounding box are printed on the filter
+log.
+
+@section blackdetect
+
+Detect video intervals that are (almost) completely black. Can be
+useful to detect chapter transitions, commercials, or invalid
+recordings. Output lines contains the time for the start, end and
+duration of the detected black interval expressed in seconds.
+
+In order to display the output lines, you need to set the loglevel at
+least to the AV_LOG_INFO value.
+
+This filter accepts a list of options in the form of
+@var{key}=@var{value} pairs separated by ":". A description of the
+accepted options follows.
+
+@table @option
+@item black_min_duration, d
+Set the minimum detected black duration expressed in seconds. It must
+be a non-negative floating point number.
+
+Default value is 2.0.
+
+@item picture_black_ratio_th, pic_th
+Set the threshold for considering a picture "black".
+Express the minimum value for the ratio:
+@example
+@var{nb_black_pixels} / @var{nb_pixels}
+@end example
+
+for which a picture is considered black.
+Default value is 0.98.
+
+@item pixel_black_th, pix_th
+Set the threshold for considering a pixel "black".
+
+The threshold expresses the maximum pixel luminance value for which a
+pixel is considered "black". The provided value is scaled according to
+the following equation:
+@example
+@var{absolute_threshold} = @var{luminance_minimum_value} + @var{pixel_black_th} * @var{luminance_range_size}
+@end example
+
+@var{luminance_range_size} and @var{luminance_minimum_value} depend on
+the input video format, the range is [0-255] for YUV full-range
+formats and [16-235] for YUV non full-range formats.
+
+Default value is 0.10.
+@end table
+
+The following example sets the maximum pixel threshold to the minimum
+value, and detects only black intervals of 2 or more seconds:
+@example
+blackdetect=d=2:pix_th=0.00
+@end example
+
@section blackframe
Detect frames that are (almost) completely black. Can be useful to
@end itemize
+@section colormatrix
+
+The colormatrix filter allows conversion between any of the following color
+space: BT.709 (@var{bt709}), BT.601 (@var{bt601}), SMPTE-240M (@var{smpte240m})
+and FCC (@var{fcc}).
+
+The syntax of the parameters is @var{source}:@var{destination}:
+
+@example
+colormatrix=bt601:smpte240m
+@end example
+
@section copy
Copy the input source unchanged to the output. Mainly useful for
@section crop
-Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}.
+Crop the input video to @var{out_w}:@var{out_h}:@var{x}:@var{y}:@var{keep_aspect}
-The parameters are expressions containing the following constants:
+The @var{keep_aspect} parameter is optional, if specified and set to a
+non-zero value will force the output display aspect ratio to be the
+same of the input, by changing the output sample aspect ratio.
+
+The @var{out_w}, @var{out_h}, @var{x}, @var{y} parameters are
+expressions containing the following constants:
@table @option
@item x, y
@item tabsize
The size in number of spaces to use for rendering the tab.
Default value is 4.
+
+@item fix_bounds
+If true, check and fix text coords to avoid clipping.
@end table
The parameters for @var{x} and @var{y} are expressions containing the
frame rate (timecode only)
@end table
+If libavfilter was built with @code{--enable-fontconfig}, then
+@option{fontfile} can be a fontconfig pattern or omitted.
+
Some examples follow.
@itemize
drawtext=fontsize=60:fontfile=FreeSerif.ttf:fontcolor=green:text=g:x=(w-max_glyph_w)/2:y=h/2-ascent
@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
+
@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 fade
Apply fade-in/out effect to input video.
@var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}
@end table
+@section idet
+
+Interlaceing detect filter. This filter tries to detect if the input is
+interlaced or progressive. Top or bottom field first.
+
@section lut, lutrgb, lutyuv
Compute a look-up table for binding each pixel component input value
The list of the currently supported filters follows:
@table @var
-@item 2xsai
@item decimate
@item denoise3d
@item detc
@item ivtc
@item kerndeint
@item mcdeint
-@item mirror
@item noise
@item ow
@item palette
@item pullup
@item qp
@item rectangle
-@item remove-logo
@item rotate
@item sab
@item screenshot
@item softpulldown
@item softskip
@item spp
-@item swapuv
@item telecine
@item tile
@item tinterlace
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
overlay=main_w-overlay_w-10:main_h-overlay_h-10
# insert a transparent PNG logo in the bottom left corner of the input
-movie=logo.png [logo];
-[in][logo] overlay=10:main_h-overlay_h-10 [out]
+ffmpeg -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output
# insert 2 different transparent PNG logos (second logo on bottom
# right corner):
-movie=logo1.png [logo1];
-movie=logo2.png [logo2];
-[in][logo1] overlay=10:H-h-10 [in+logo1];
-[in+logo1][logo2] overlay=W-w-10:H-h-10 [out]
+ffmpeg -i input -i logo1 -i logo2 -filter_complex
+'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output
# add a transparent color layer on top of the main video,
# WxH specifies the size of the main input to the overlay filter
can be used to test the monowhite pixel format descriptor definition.
+@section removelogo
+
+Suppress a TV station logo, using an image file to determine which
+pixels comprise the logo. It works by filling in the pixels that
+comprise the logo with neighboring pixels.
+
+This filter requires one argument which specifies the filter bitmap
+file, which can be any image format supported by libavformat. The
+width and height of the image file must match those of the video
+stream being processed.
+
+Pixels in the provided bitmap image with a value of zero are not
+considered part of the logo, non-zero pixels are considered part of
+the logo. If you use white (255) for the logo and black (0) for the
+rest, you will be safe. For making the filter bitmap, it is
+recommended to take a screen capture of a black frame with the logo
+visible, and then using a threshold filter followed by the erode
+filter once or twice.
+
+If needed, little splotches can be fixed manually. Remember that if
+logo pixels are not covered, the filter quality will be much
+reduced. Marking too many pixels as part of the logo does not hurt as
+much, but it will increase the amount of blurring needed to cover over
+the image and will destroy more information than necessary, and extra
+pixels will slow things down on a large logo.
+
@section scale
Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format.
+The scale filter forces the output display aspect ratio to be the same
+of the input, by changing the output sample aspect ratio.
+
The parameters @var{width} and @var{height} are expressions containing
the following constants:
are flagged as interlaced or not
@end table
+Unless @var{interl} is set to one of the above options, interlaced scaling will not be used.
+
Some examples follow:
@example
# scale the input video to a size of 200x100.
# the above is the same as
scale=2*in_w:2*in_h
+# scale the input to 2x with forced interlaced scaling
+scale=2*iw:2*ih:interl=1
+
# scale the input to half size
scale=iw/2:ih/2
For example to change the display aspect ratio to 16:9, specify:
@example
setdar=16:9
-# the above is equivalent to
+@end example
+
+The example above is equivalent to:
+@example
setdar=1.77777
@end example
setsar=10:11
@end example
+@section setfield
+
+Force field for the output video frame.
+
+The @code{setfield} filter marks the interlace type field for the
+output frames. It does not change the input frame, but only sets the
+corresponding property, which affects how the frame is treated by
+following filters (e.g. @code{fieldorder} or @code{yadif}).
+
+It accepts a string parameter, which can assume the following values:
+@table @samp
+@item auto
+Keep the same field property.
+
+@item bff
+Mark the frame as bottom-field-first.
+
+@item tff
+Mark the frame as top-field-first.
+
+@item prog
+Mark the frame as progressive.
+@end table
+
@section setpts
Change the PTS (presentation timestamp) of the input video frames.
will create two separate outputs from the same input, one cropped and
one padded.
+@section super2xsai
+
+Scale the input by 2x and smooth using the Super2xSaI (Scale and
+Interpolate) pixel art scaling algorithm.
+
+Useful for enlarging pixel art images without reducing sharpness.
+
+@section swapuv
+Swap U & V plane.
+
@section thumbnail
Select the most representative frame in a given sequence of consecutive frames.
ffmpeg -i in.avi -vf thumbnail,scale=300:200 -frames:v 1 out.png
@end example
+@section tile
+
+Tile several successive frames together.
+
+It accepts as argument the tile size (i.e. the number of lines and columns)
+in the form "@var{w}x@var{h}".
+
+For example, produce 8×8 PNG tiles of all keyframes (@option{-skip_frame
+nokey}) in a movie:
+@example
+ffmpeg -skip_frame nokey -i file.avi -vf 'scale=128:72,tile=8x8' -an -vsync 0 keyframes%03d.png
+@end example
+The @option{-vsync 0} is necessary to prevent @command{ffmpeg} from
+duplicating each output frame to accomodate the originally detected frame
+rate.
+
@section tinterlace
Perform various types of temporal field interlacing.
the best suited video stream will be automatically selected. Default
value is "-1".
+@item loop
+Specifies how many times to read the video stream in sequence.
+If the value is less than 1, the stream will be read again and again.
+Default value is "1".
+
+Note that when the movie is looped the source timestamps are not
+changed, so it will generate non monotonically increasing timestamps.
@end table
This filter allows to overlay a second video on top of main input of
tools.
@c man end VIDEO SINKS
-
projects / ffmpeg / blobdiff