@section Filtergraph syntax
A filtergraph can be represented using a textual representation, which
-is recognized by the @code{-vf} and @code{-af} options of the ff*
+is recognized by the @code{-vf} option of the ff*
tools, and by the @code{avfilter_graph_parse()} function defined in
@file{libavfilter/avfiltergraph.h}.
the corresponding numeric value defined in @file{libavutil/samplefmt.h}.
@var{channel_layout} specifies the channel layout, and can be a string
-or the corresponding number value defined in @file{libavutil/chlayout.h}.
+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".
@item pos
position of the frame in the input stream, -1 if this information in
-unavailable and/or meanigless (for example in case of synthetic audio)
+unavailable and/or meaningless (for example in case of synthetic audio)
@item fmt
sample format name
if the packing format is planar, 0 if packed
@item checksum
-Adler-32 checksum of all the planes of the input frame
+Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
@item plane_checksum
-Adler-32 checksum for each input frame plane, expressed in the form
-"[@var{c0} @var{c1} @var{c2} @var{c3} @var{c4} @var{c5} @var{c6} @var{c7}]"
+Adler-32 checksum (printed in hexadecimal) for each input frame plane,
+expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3} @var{c4} @var{c5}
+@var{c6} @var{c7}]"
@end table
+@section earwax
+
+Make audio easier to listen to on headphones.
+
+This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
+so that when listened to on headphones the stereo image is moved from
+inside your head (standard for headphones) to outside and in front of
+the listener (standard for speakers).
+
+Ported from SoX.
+
+@section pan
+
+Mix channels with specific gain levels. The filter accepts the output
+channel layout followed by a set of channels definitions.
+
+The filter accepts parameters of the form:
+"@var{l}:@var{outdef}:@var{outdef}:..."
+
+@table @option
+@item l
+output channel layout or number of channels
+
+@item outdef
+output channel specification, of the form:
+"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
+
+@item out_name
+output channel to define, either a channel name (FL, FR, etc.) or a channel
+number (c0, c1, etc.)
+
+@item gain
+multiplicative coefficient for the channel, 1 leaving the volume unchanged
+
+@item in_name
+input channel to use, see out_name for details; it is not possible to mix
+named and numbered input channels
+@end table
+
+If the `=' in a channel specification is replaced by `<', then the gains for
+that specification will be renormalized so that the total is 1, thus
+avoiding clipping noise.
+
+For example, if you want to down-mix from stereo to mono, but with a bigger
+factor for the left channel:
+@example
+pan=1:c0=0.9*c0+0.1*c1
+@end example
+
+A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
+7-channels surround:
+@example
+pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+@end example
+
+Note that @file{ffmpeg} integrates a default down-mix (and up-mix) system
+that should be preferred (see "-ac" option) unless you have very specific
+needs.
+
+@section volume
+
+Adjust the input audio volume.
+
+The filter accepts exactly one parameter @var{vol}, which expresses
+how the audio volume will be increased or decreased.
+
+Output values are clipped to the maximum value.
+
+If @var{vol} is expressed as a decimal number, and the output audio
+volume is given by the relation:
+@example
+@var{output_volume} = @var{vol} * @var{input_volume}
+@end example
+
+If @var{vol} is expressed as a decimal number followed by the string
+"dB", the value represents the requested change in decibels of the
+input audio power, and the output audio volume is given by the
+relation:
+@example
+@var{output_volume} = 10^(@var{vol}/20) * @var{input_volume}
+@end example
+
+Otherwise @var{vol} is considered an expression and its evaluated
+value is used for computing the output audio volume according to the
+first relation.
+
+Default value for @var{vol} is 1.0.
+
+@subsection Examples
+
+@itemize
+@item
+Half the input audio volume:
+@example
+volume=0.5
+@end example
+
+The above example is equivalent to:
+@example
+volume=1/2
+@end example
+
+@item
+Decrease input audio power by 12 decibels:
+@example
+volume=-12dB
+@end example
+@end itemize
+
@c man end AUDIO FILTERS
@chapter Audio Sources
@table @option
+@item duration, d
+Set the minimum duration of the sourced audio. See the function
+@code{av_parse_time()} for the accepted format.
+Note that the resulting duration may be greater than the specified
+duration, as the generated audio is always cut at the end of a
+complete frame.
+
+If not specified, or the expressed duration is negative, the audio is
+supposed to be generated forever.
+
@item nb_samples, n
Set the number of samples per channel per each output frame,
default to 1024.
@item
-Generate a sin signal with frequence of 440 Hz, set sample rate to
+Generate a sin signal with frequency of 440 Hz, set sample rate to
8000 Hz:
@example
aevalsrc="sin(440*2*PI*t)::s=8000"
Below is a description of the currently available video filters.
+@section ass
+
+Draw ASS (Advanced Substation Alpha) subtitles on top of input video
+using the libass library.
+
+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.
+
+For example, to render the file @file{sub.ass} on top of the input
+video, use the command:
+@example
+ass=sub.ass
+@end example
+
@section blackframe
Detect frames that are (almost) completely black. Can be useful to
constants:
@table @option
@item w, h
-the input width and heigth in pixels
+the input width and height in pixels
@item cw, ch
the input chroma image width and height in pixels
@table @option
@item x, y, w, h
-Specify a rectangular area where to limit the sarch for motion
+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
following constants:
@table @option
-@item w, h
-the input width and heigth
+@item W, H
+the input width and height
@item tw, text_w
the width of the rendered text
@item t
timestamp expressed in seconds, NAN if the input timestamp is unknown
+
+@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
+
+@item r, rate
+frame rate (timecode only)
@end table
Some examples follow.
Apply fade-in/out effect to input video.
It accepts the parameters:
-@var{type}:@var{start_frame}:@var{nb_frames}
+@var{type}:@var{start_frame}:@var{nb_frames}[:@var{options}]
@var{type} specifies if the effect type, can be either "in" for
fade-in, or "out" for a fade-out effect.
will have the same intensity as the input video, at the end of the
fade-out transition the output video will be completely black.
+@var{options} is an optional sequence of @var{key}=@var{value} pairs,
+separated by ":". The description of the accepted options follows.
+
+@table @option
+
+@item type, t
+See @var{type}.
+
+@item start_frame, s
+See @var{start_frame}.
+
+@item nb_frames, n
+See @var{nb_frames}.
+
+@item alpha
+If set to 1, fade only alpha channel, if one exists on the input.
+Default value is 0.
+@end table
+
A few usage examples follow, usable too as test scenarios.
@example
# fade in first 30 frames of video
# make first 5 frames black, then fade in from frame 5-24
fade=in:5:20
+
+# fade in alpha over first 25 frames of video
+fade=in:0:25:alpha=1
@end example
@section fieldorder
For example:
@example
-./ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
+ffmpeg -i in.vob -vf "fieldorder=bff" out.dv
@end example
@section fifo
@section gradfun
Fix the banding artifacts that are sometimes introduced into nearly flat
-regions by truncation to 8bit colordepth.
+regions by truncation to 8bit color depth.
Interpolate the gradients that should go where the bands are, and
dither them.
Flip the input video horizontally.
-For example to horizontally flip the video in input with
-@file{ffmpeg}:
+For example to horizontally flip the input video with @command{ffmpeg}:
@example
ffmpeg -i in.avi -vf "hflip" out.avi
@end example
@table @option
@item w, h
-the input width and heigth
+the input width and height
@item val
input value for the pixel component
filter. If not specified the default values are assumed.
Refer to the official libopencv documentation for more precise
-informations:
+information:
@url{http://opencv.willowgarage.com/documentation/c/image_filtering.html}
Follows the list of supported libopencv filters.
@var{struct_el} represents a structuring element, and has the syntax:
@var{cols}x@var{rows}+@var{anchor_x}x@var{anchor_y}/@var{shape}
-@var{cols} and @var{rows} represent the number of colums and rows of
+@var{cols} and @var{rows} represent the number of columns and rows of
the structuring element, @var{anchor_x} and @var{anchor_y} the anchor
point, and @var{shape} the shape for the structuring element, and
can be one of the values "rect", "cross", "ellipse", "custom".
These parameters correspond to the parameters assigned to the
libopencv function @code{cvSmooth}.
+@anchor{overlay}
@section overlay
Overlay one video on top of another.
It takes two inputs and one output, the first input is the "main"
video on which the second input is overlayed.
-It accepts the parameters: @var{x}:@var{y}.
+It accepts the parameters: @var{x}:@var{y}[:@var{options}].
@var{x} is the x coordinate of the overlayed video on the main video,
-@var{y} is the y coordinate. The parameters are expressions containing
+@var{y} is the y coordinate. @var{x} and @var{y} are expressions containing
the following parameters:
@table @option
same as @var{overlay_w} and @var{overlay_h}
@end table
+@var{options} is an optional list of @var{key}=@var{value} pairs,
+separated by ":".
+
+The description of the accepted options follows.
+
+@table @option
+@item rgb
+If set to 1, force the filter to accept inputs in the RGB
+color space. Default value is 0.
+@end table
+
Be aware that frames are taken from each input video in timestamp
order, hence, if their initial timestamps differ, it is a a good idea
to pass the two inputs through a @var{setpts=PTS-STARTPTS} filter to
color=red@.3:WxH [over]; [in][over] overlay [out]
@end example
-You can chain togheter more overlays but the efficiency of such
+You can chain together more overlays but the efficiency of such
approach is yet to be tested.
@section pad
is used for the output.
The @var{width} expression can reference the value set by the
-@var{height} expression, and viceversa.
+@var{height} expression, and vice versa.
The default value of @var{width} and @var{height} is 0.
with respect to the top/left border of the output image.
The @var{x} expression can reference the value set by the @var{y}
-expression, and viceversa.
+expression, and vice versa.
The default value of @var{x} and @var{y} is 0.
@section scale
-Scale the input video to @var{width}:@var{height} and/or convert the image format.
+Scale the input video to @var{width}:@var{height}[:@var{interl}=@{1|-1@}] and/or convert the image format.
The parameters @var{width} and @var{height} are expressions containing
the following constants:
The default value of @var{width} and @var{height} is 0.
+Valid values for the optional parameter @var{interl} are:
+
+@table @option
+@item 1
+force interlaced aware scaling
+
+@item -1
+select interlaced aware scaling depending on whether the source frames
+are flagged as interlaced or not
+@end table
+
Some examples follow:
@example
# scale the input video to a size of 200x100.
@item pos
position of the frame in the input stream, -1 if this information in
-unavailable and/or meanigless (for example in case of synthetic video)
+unavailable and/or meaningless (for example in case of synthetic video)
@item fmt
pixel format name
@file{libavutil/avutil.h}.
@item checksum
-Adler-32 checksum of all the planes of the input frame
+Adler-32 checksum (printed in hexadecimal) of all the planes of the input frame
@item plane_checksum
-Adler-32 checksum of each plane of the input frame, expressed in the form
-"[@var{c0} @var{c1} @var{c2} @var{c3}]"
+Adler-32 checksum (printed in hexadecimal) of each plane of the input frame,
+expressed in the form "[@var{c0} @var{c1} @var{c2} @var{c3}]"
@end table
@section slicify
slices.
@example
-./ffmpeg -i in.avi -vf "slicify=32" out.avi
+ffmpeg -i in.avi -vf "slicify=32" out.avi
@end example
The filter accepts the slice height as parameter. If the parameter is
unsharp=7:7:-2:7:7:-2
# Use the default values with @command{ffmpeg}
-./ffmpeg -i in.avi -vf "unsharp" out.mp4
+ffmpeg -i in.avi -vf "unsharp" out.mp4
@end example
@section vflip
Flip the input video vertically.
@example
-./ffmpeg -i in.avi -vf "vflip" out.avi
+ffmpeg -i in.avi -vf "vflip" out.avi
@end example
@section yadif
It accepts the following parameters:
@var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}:@var{scale_params}
-All the parameters but @var{scale_params} need to be explicitely
+All the parameters but @var{scale_params} need to be explicitly
defined.
Follows the list of the accepted parameters.
buffer=320:240:6:1:24:1:1
@end example
+@section cellauto
+
+Create a pattern generated by an elementary cellular automaton.
+
+The initial state of the cellular automaton can be defined through the
+@option{filename}, and @option{pattern} options. If such options are
+not specified an initial state is created randomly.
+
+At each new frame a new row in the video is filled with the result of
+the cellular automaton next generation. The behavior when the whole
+frame is filled is defined by the @option{scroll} option.
+
+This source 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 filename, f
+Read the initial cellular automaton state, i.e. the starting row, from
+the specified file.
+In the file, each non-whitespace character is considered an alive
+cell, a newline will terminate the row, and further characters in the
+file will be ignored.
+
+@item pattern, p
+Read the initial cellular automaton state, i.e. the starting row, from
+the specified string.
+
+Each non-whitespace character in the string is considered an alive
+cell, a newline will terminate the row, and further characters in the
+string will be ignored.
+
+@item rate, r
+Set the video rate, that is the number of frames generated per second.
+Default is 25.
+
+@item random_fill_ratio, ratio
+Set the random fill ratio for the initial cellular automaton row. It
+is a floating point number value ranging from 0 to 1, defaults to
+1/PHI.
+
+This option is ignored when a file or a pattern is specified.
+
+@item random_seed, seed
+Set the seed for filling randomly the initial row, must be an integer
+included between 0 and UINT32_MAX. If not specified, or if explicitly
+set to -1, the filter will try to use a good random seed on a best
+effort basis.
+
+@item rule
+Set the cellular automaton rule, it is a number ranging from 0 to 255.
+Default value is 110.
+
+@item size, s
+Set the size of the output video.
+
+If @option{filename} or @option{pattern} is specified, the size is set
+by default to the width of the specified initial state row, and the
+height is set to @var{width} * PHI.
+
+If @option{size} is set, it must contain the width of the specified
+pattern string, and the specified pattern will be centered in the
+larger row.
+
+If a filename or a pattern string is not specified, the size value
+defaults to "320x518" (used for a randomly generated initial state).
+
+@item scroll
+If set to 1, scroll the output upward when all the rows in the output
+have been already filled. If set to 0, the new generated row will be
+written over the top row just after the bottom row is filled.
+Defaults to 1.
+
+@item start_full, full
+If set to 1, completely fill the output with generated rows before
+outputting the first frame.
+This is the default behavior, for disabling set the value to 0.
+
+@item stitch
+If set to 1, stitch the left and right row edges together.
+This is the default behavior, for disabling set the value to 0.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Read the initial state from @file{pattern}, and specify an output of
+size 200x400.
+@example
+cellauto=f=pattern:s=200x400
+@end example
+
+@item
+Generate a random initial row with a width of 200 cells, with a fill
+ratio of 2/3:
+@example
+cellauto=ratio=2/3:s=200x200
+@end example
+
+@item
+Create a pattern generated by rule 18 starting by a single alive cell
+centered on an initial row with width 100:
+@example
+cellauto=p=@@:s=100x400:full=0:rule=18
+@end example
+
+@item
+Specify a more elaborated initial pattern:
+@example
+cellauto=p='@@@@ @@ @@@@':s=100x400:full=0:rule=18
+@end example
+
+@end itemize
+
@section color
Provide an uniformly colored input.
will generate a "dc_luma" test pattern.
-@section nullsrc
-
-Null video source, never return images. It is mainly useful as a
-template and to be employed in analysis / debugging tools.
-
-It accepts as optional parameter a string of the form
-@var{width}:@var{height}:@var{timebase}.
-
-@var{width} and @var{height} specify the size of the configured
-source. The default values of @var{width} and @var{height} are
-respectively 352 and 288 (corresponding to the CIF size format).
-
-@var{timebase} specifies an arithmetic expression representing a
-timebase. The expression can contain the constant
-"AVTB" (the default timebase), and defaults to the value "AVTB".
-
@section frei0r_src
Provide a frei0r source.
Some examples follow:
@example
-# generate a frei0r partik0l source with size 200x200 and framerate 10
+# generate a frei0r partik0l source with size 200x200 and frame rate 10
# which is overlayed on the overlay filter main input
frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
@end example
-@section rgbtestsrc, testsrc
+@section life
+
+Generate a life pattern.
+
+This source is based on a generalization of John Conway's life game.
+
+The sourced input represents a life grid, each pixel represents a cell
+which can be in one of two possible states, alive or dead. Every cell
+interacts with its eight neighbours, which are the cells that are
+horizontally, vertically, or diagonally adjacent.
+
+At each interaction the grid evolves according to the adopted rule,
+which specifies the number of neighbor alive cells which will make a
+cell stay alive or born. The @option{rule} option allows to specify
+the rule to adopt.
+
+This source 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 filename, f
+Set the file from which to read the initial grid state. In the file,
+each non-whitespace character is considered an alive cell, and newline
+is used to delimit the end of each row.
+
+If this option is not specified, the initial grid is generated
+randomly.
+
+@item rate, r
+Set the video rate, that is the number of frames generated per second.
+Default is 25.
+
+@item random_fill_ratio, ratio
+Set the random fill ratio for the initial random grid. It is a
+floating point number value ranging from 0 to 1, defaults to 1/PHI.
+It is ignored when a file is specified.
+
+@item random_seed, seed
+Set the seed for filling the initial random grid, must be an integer
+included between 0 and UINT32_MAX. If not specified, or if explicitly
+set to -1, the filter will try to use a good random seed on a best
+effort basis.
+
+@item rule
+Set the life rule.
+
+A rule can be specified with a code of the kind "S@var{NS}/B@var{NB}",
+where @var{NS} and @var{NB} are sequences of numbers in the range 0-8,
+@var{NS} specifies the number of alive neighbor cells which make a
+live cell stay alive, and @var{NB} the number of alive neighbor cells
+which make a dead cell to become alive (i.e. to "born").
+"s" and "b" can be used in place of "S" and "B", respectively.
+
+Alternatively a rule can be specified by an 18-bits integer. The 9
+high order bits are used to encode the next cell state if it is alive
+for each number of neighbor alive cells, the low order bits specify
+the rule for "borning" new cells. Higher order bits encode for an
+higher number of neighbor cells.
+For example the number 6153 = @code{(12<<9)+9} specifies a stay alive
+rule of 12 and a born rule of 9, which corresponds to "S23/B03".
+
+Default value is "S23/B3", which is the original Conway's game of life
+rule, and will keep a cell alive if it has 2 or 3 neighbor alive
+cells, and will born a new cell if there are three alive cells around
+a dead cell.
+
+@item size, s
+Set the size of the output video.
+
+If @option{filename} is specified, the size is set by default to the
+same size of the input file. If @option{size} is set, it must contain
+the size specified in the input file, and the initial grid defined in
+that file is centered in the larger resulting area.
+
+If a filename is not specified, the size value defaults to "320x240"
+(used for a randomly generated initial grid).
+
+@item stitch
+If set to 1, stitch the left and right grid edges together, and the
+top and bottom edges also. Defaults to 1.
+
+@item mold
+Set cell mold speed. If set, a dead cell will go from @option{death_color} to
+@option{mold_color} with a step of @option{mold}. @option{mold} can have a
+value from 0 to 255.
+
+@item life_color
+Set the color of living (or new born) cells.
+
+@item death_color
+Set the color of dead cells. If @option{mold} is set, this is the first color
+used to represent a dead cell.
+
+@item mold_color
+Set mold color, for definitely dead and moldy cells.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Read a grid from @file{pattern}, and center it on a grid of size
+300x300 pixels:
+@example
+life=f=pattern:s=300x300
+@end example
+
+@item
+Generate a random grid of size 200x200, with a fill ratio of 2/3:
+@example
+life=ratio=2/3:s=200x200
+@end example
+
+@item
+Specify a custom rule for evolving a randomly generated grid:
+@example
+life=rule=S14/B34
+@end example
+
+@item
+Full example with slow death effect (mold) using @command{ffplay}:
+@example
+ffplay -f lavfi life=s=300x200:mold=10:r=60:ratio=0.1:death_color=#C83232:life_color=#00ff00,scale=1200:800:flags=16
+@end example
+@end itemize
+
+@section nullsrc, rgbtestsrc, testsrc
+
+The @code{nullsrc} source returns unprocessed video frames. It is
+mainly useful to be employed in analysis / debugging tools, or as the
+source for filters which ignore the input data.
The @code{rgbtestsrc} source generates an RGB test pattern useful for
detecting RGB vs BGR issues. You should see a red, green and blue
color pattern, a scrolling gradient and a timestamp. This is mainly
intended for testing purposes.
-Both sources accept an optional sequence of @var{key}=@var{value} pairs,
+These sources accept an optional sequence of @var{key}=@var{value} pairs,
separated by ":". The description of the accepted options follows.
@table @option
@item size, s
Specify the size of the sourced video, it may be a string of the form
-@var{width}x@var{heigth}, or the name of a size abbreviation. The
+@var{width}x@var{height}, or the name of a size abbreviation. The
default value is "320x240".
@item rate, r
@end example
will generate a video with a duration of 5.3 seconds, with size
-176x144 and a framerate of 10 frames per second.
+176x144 and a frame rate of 10 frames per second.
+
+If the input content is to be ignored, @code{nullsrc} can be used. The
+following command generates noise in the luminance plane by employing
+the @code{mp=geq} filter:
+@example
+nullsrc=s=256x256, mp=geq=random(1)*255:128:128
+@end example
@c man end VIDEO SOURCES
projects / ffmpeg / blobdiff