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
Convert the input audio format to the specified formats.
The filter accepts a string of the form:
-"@var{sample_format}:@var{channel_layout}:@var{packing_format}".
+"@var{sample_format}:@var{channel_layout}".
-@var{sample_format} specifies the sample format, and can be a string or
-the corresponding numeric value defined in @file{libavutil/samplefmt.h}.
+@var{sample_format} specifies the sample format, and can be a string or the
+corresponding numeric value defined in @file{libavutil/samplefmt.h}. Use 'p'
+suffix for a planar sample format.
@var{channel_layout} specifies the channel layout, and can be a string
or the corresponding number value defined in @file{libavutil/audioconvert.h}.
-@var{packing_format} specifies the type of packing in output, can be one
-of "planar" or "packed", or the corresponding numeric values "0" or "1".
-
The special parameter "auto", signifies that the filter will
automatically select the output format depending on the output filter.
@itemize
@item
-Convert input to unsigned 8-bit, stereo, packed:
+Convert input to float, planar, stereo:
@example
-aconvert=u8:stereo:packed
+aconvert=fltp:stereo
@end example
@item
-Convert input to unsigned 8-bit, automatically select out channel layout
-and packing format:
+Convert input to unsigned 8-bit, automatically select out channel layout:
@example
-aconvert=u8:auto:auto
+aconvert=u8:auto
@end example
@end itemize
amovie=left.wav [l] ; amovie=right.mp3 [r] ; [l] [r] amerge
@end example
+If you need to do multiple merges (for instance multiple mono audio streams in
+a single video media), you can do:
+@example
+ffmpeg -f lavfi -i "
+amovie=input.mkv:si=0 [a0];
+amovie=input.mkv:si=1 [a1];
+amovie=input.mkv:si=2 [a2];
+amovie=input.mkv:si=3 [a3];
+amovie=input.mkv:si=4 [a4];
+amovie=input.mkv:si=5 [a5];
+[a0][a1] amerge [x0];
+[x0][a2] amerge [x1];
+[x1][a3] amerge [x2];
+[x2][a4] amerge [x3];
+[x3][a5] amerge" -c:a pcm_s16le output.mkv
+@end example
+
@section anull
Pass the audio source unchanged to the output.
Mix channels with specific gain levels. The filter accepts the output
channel layout followed by a set of channels definitions.
+This filter is also designed to remap efficiently the channels of an audio
+stream.
+
The filter accepts parameters of the form:
"@var{l}:@var{outdef}:@var{outdef}:..."
that specification will be renormalized so that the total is 1, thus
avoiding clipping noise.
+@subsection Mixing examples
+
For example, if you want to down-mix from stereo to mono, but with a bigger
factor for the left channel:
@example
that should be preferred (see "-ac" option) unless you have very specific
needs.
+@subsection Remapping examples
+
+The channel remapping will be effective if, and only if:
+
+@itemize
+@item gain coefficients are zeroes or ones,
+@item only one input per channel output,
+@end itemize
+
+If all these conditions are satisfied, the filter will notify the user ("Pure
+channel mapping detected"), and use an optimized and lossless method to do the
+remapping.
+
+For example, if you have a 5.1 source and want a stereo audio stream by
+dropping the extra channels:
+@example
+pan="stereo: c0=FL : c1=FR"
+@end example
+
+Given the same source, you can also switch front left and front right channels
+and keep the input channel layout:
+@example
+pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
+@end example
+
+If the input is a stereo audio stream, you can mute the front left channel (and
+still keep the stereo channel layout) with:
+@example
+pan="stereo:c1=c1"
+@end example
+
+Still with a stereo audio stream input, you can copy the right channel in both
+front left and right:
+@example
+pan="stereo: c0=FR : c1=FR"
+@end example
+
@section silencedetect
Detect silence in an audio stream.
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
@item timecode
initial timecode representation in "hh:mm:ss[:;.]ff" format. It can be used
with or without text parameter. @var{rate} option must be specified.
-Note that timecode options are @emph{not} effective if FFmpeg is build with
-@code{--disable-avcodec}.
@item r, rate
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:
@item dar
input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
-@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.
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
select='isnan(prev_selected_t)+gte(t-prev_selected_t\,10)'
@end example
-@anchor{setdar}
-@section setdar
+@section setdar, setsar
-Set the Display Aspect Ratio for the filter output video.
+The @code{setdar} filter sets the Display Aspect Ratio for the filter
+output video.
This is done by changing the specified Sample (aka Pixel) Aspect
Ratio, according to the following equation:
-@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
+@example
+@var{DAR} = @var{HORIZONTAL_RESOLUTION} / @var{VERTICAL_RESOLUTION} * @var{SAR}
+@end example
+
+Keep in mind that the @code{setdar} filter does not modify the pixel
+dimensions of the video frame. Also the display aspect ratio set by
+this filter may be changed by later filters in the filterchain,
+e.g. in case of scaling or if another "setdar" or a "setsar" filter is
+applied.
-Keep in mind that this filter does not modify the pixel dimensions of
-the video frame. Also the display aspect ratio set by this filter may
-be changed by later filters in the filterchain, e.g. in case of
-scaling or if another "setdar" or a "setsar" filter is applied.
+The @code{setsar} filter sets the Sample (aka Pixel) Aspect Ratio for
+the filter output video.
+
+Note that as a consequence of the application of this filter, the
+output display aspect ratio will change according to the equation
+above.
-The filter accepts a parameter string which represents the wanted
-display aspect ratio.
-The parameter can be a floating point number string, or an expression
-of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
-numerator and denominator of the aspect ratio.
-If the parameter is not specified, it is assumed the value "0:1".
+Keep in mind that the sample aspect ratio set by the @code{setsar}
+filter may be changed by later filters in the filterchain, e.g. if
+another "setsar" or a "setdar" filter is applied.
+
+The @code{setdar} and @code{setsar} filters accept a parameter string
+which represents the wanted aspect ratio. The parameter can
+be a floating point number string, an expression, or a string of the form
+@var{num}:@var{den}, where @var{num} and @var{den} are the numerator
+and denominator of the aspect ratio. If the parameter is not
+specified, it is assumed the value "0:1".
For example to change the display aspect ratio to 16:9, specify:
@example
setdar=16:9
-# the above is equivalent to
+@end example
+
+The example above is equivalent to:
+@example
setdar=1.77777
@end example
-See also the @ref{setsar} filter documentation.
+To change the sample aspect ratio to 10:11, specify:
+@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
setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
@end example
-@anchor{setsar}
-@section setsar
-
-Set the Sample (aka Pixel) Aspect Ratio for the filter output video.
-
-Note that as a consequence of the application of this filter, the
-output display aspect ratio will change according to the following
-equation:
-@math{DAR = HORIZONTAL_RESOLUTION / VERTICAL_RESOLUTION * SAR}
-
-Keep in mind that the sample aspect ratio set by this filter may be
-changed by later filters in the filterchain, e.g. if another "setsar"
-or a "setdar" filter is applied.
-
-The filter accepts a parameter string which represents the wanted
-sample aspect ratio.
-The parameter can be a floating point number string, or an expression
-of the form @var{num}:@var{den}, where @var{num} and @var{den} are the
-numerator and denominator of the aspect ratio.
-If the parameter is not specified, it is assumed the value "0:1".
-
-For example to change the sample aspect ratio to 10:11, specify:
-@example
-setsar=10:11
-@end example
-
@section settb
Set the timebase to use for the output frames timestamps.
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
@item sar
Set the sample aspect ratio of the sourced video.
-@item duration
+@item duration, d
Set the video duration of the sourced video. The accepted syntax is:
@example
[-]HH[:MM[:SS[.m...]]]
If not specified, or the expressed duration is negative, the video is
supposed to be generated forever.
+
+@item decimals, n
+Set the number of decimals to show in the timestamp, only used in the
+@code{testsrc} source.
+
+The displayed timestamp value will correspond to the original
+timestamp value multiplied by the power of 10 of the specified
+value. Default value is 0.
@end table
For example the following:
tools.
@c man end VIDEO SINKS
-
projects / ffmpeg / blobdiff