]> git.sesse.net Git - ffmpeg/blobdiff - doc/filters.texi
Fix various if parenthesis misplacements.
[ffmpeg] / doc / filters.texi
index bd15b5ead4db971ddb986bbfd9c120033798428b..cefb8ad0c3235a48166d72fac2cfb00d1afb557b 100644 (file)
@@ -110,7 +110,7 @@ The filter accepts a string of the form:
 the corresponding numeric value defined in @file{libavutil/samplefmt.h}.
 
 @var{channel_layout} specifies the channel layout, and can be a string
 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".
 
 @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".
@@ -198,7 +198,7 @@ seconds
 
 @item pos
 position of the frame in the input stream, -1 if this information in
 
 @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
 
 @item fmt
 sample format name
@@ -216,13 +216,123 @@ sample rate for the audio frame
 if the packing format is planar, 0 if packed
 
 @item checksum
 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
 
 @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
 
 @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
 @c man end AUDIO FILTERS
 
 @chapter Audio Sources
@@ -275,6 +385,86 @@ equivalent to:
 abuffer=44100:1:3:1
 @end example
 
 abuffer=44100:1:3:1
 @end example
 
+@section aevalsrc
+
+Generate an audio signal specified by an expression.
+
+This source accepts in input one or more expressions (one for each
+channel), which are evaluated and used to generate a corresponding
+audio signal.
+
+It accepts the syntax: @var{exprs}[::@var{options}].
+@var{exprs} is a list of expressions separated by ":", one for each
+separate channel. The output channel layout depends on the number of
+provided expressions, up to 8 channels are supported.
+
+@var{options} is an optional sequence of @var{key}=@var{value} pairs,
+separated by ":".
+
+The description of the accepted options follows.
+
+@table @option
+
+@item nb_samples, n
+Set the number of samples per channel per each output frame,
+default to 1024.
+
+@item sample_rate, s
+Specify the sample rate, default to 44100.
+@end table
+
+Each expression in @var{exprs} can contain the following constants:
+
+@table @option
+@item n
+number of the evaluated sample, starting from 0
+
+@item t
+time of the evaluated sample expressed in seconds, starting from 0
+
+@item s
+sample rate
+
+@end table
+
+@subsection Examples
+
+@itemize
+
+@item
+Generate silence:
+@example
+aevalsrc=0
+@end example
+
+@item
+
+Generate a sin signal with frequence of 440 Hz, set sample rate to
+8000 Hz:
+@example
+aevalsrc="sin(440*2*PI*t)::s=8000"
+@end example
+
+@item
+Generate white noise:
+@example
+aevalsrc="-2+random(0)"
+@end example
+
+@item
+Generate an amplitude modulated signal:
+@example
+aevalsrc="sin(10*2*PI*t)*sin(880*2*PI*t)"
+@end example
+
+@item
+Generate 2.5 Hz binaural beats on a 360 Hz carrier:
+@example
+aevalsrc="0.1*sin(2*PI*(360-2.5/2)*t) : 0.1*sin(2*PI*(360+2.5/2)*t)"
+@end example
+
+@end itemize
+
 @section amovie
 
 Read an audio stream from a movie container.
 @section amovie
 
 Read an audio stream from a movie container.
@@ -432,7 +622,7 @@ horizontal and vertical chroma subsample values. For example for the
 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 @end table
 
 pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 @end table
 
-The radius must be a non-negative number, and must be not greater than
+The radius 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.
 
 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.
 
@@ -664,6 +854,76 @@ delogo=x=0:y=0:w=100:h=77:band=10
 
 @end itemize
 
 
 @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 parameters as a string of the form
+"@var{x}:@var{y}:@var{w}:@var{h}:@var{rx}:@var{ry}:@var{edge}:@var{blocksize}:@var{contrast}:@var{search}:@var{filename}"
+
+A description of the accepted parameters follows.
+
+@table @option
+
+@item x, y, w, 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, 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. An integer from 0 to 3 as follows:
+@table @option
+@item 0
+Fill zeroes at blank locations
+@item 1
+Original image at blank locations
+@item 2
+Extruded edge value at blank locations
+@item 3
+Mirrored edge at blank locations
+@end table
+
+The default setting is mirror edge at blank locations.
+
+@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 0 = exhaustive search, 1 = less exhaustive
+search. Default - exhaustive search.
+
+@item filename
+If set then a detailed log of the motion search is written to the
+specified file.
+
+@end table
+
 @section drawbox
 
 Draw a colored box on the input image.
 @section drawbox
 
 Draw a colored box on the input image.
@@ -927,7 +1187,7 @@ For more information about libfreetype, check:
 Apply fade-in/out effect to input video.
 
 It accepts the parameters:
 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.
 
 @var{type} specifies if the effect type, can be either "in" for
 fade-in, or "out" for a fade-out effect.
@@ -940,6 +1200,25 @@ 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.
 
 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
 A few usage examples follow, usable too as test scenarios.
 @example
 # fade in first 30 frames of video
@@ -953,6 +1232,9 @@ fade=in:0:25, fade=out:975:25
 
 # make first 5 frames black, then fade in from frame 5-24
 fade=in:5:20
 
 # 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
 @end example
 
 @section fieldorder
@@ -985,7 +1267,7 @@ which is bottom field first.
 
 For example:
 @example
 
 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
 @end example
 
 @section fifo
@@ -1480,10 +1762,10 @@ 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 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{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
 the following parameters:
 
 @table @option
@@ -1500,6 +1782,17 @@ overlay input width and height
 same as @var{overlay_w} and @var{overlay_h}
 @end table
 
 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
+colorspace. 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
 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
@@ -1528,7 +1821,7 @@ movie=logo2.png [logo2];
 color=red@.3:WxH [over]; [in][over] overlay [out]
 @end example
 
 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
 approach is yet to be tested.
 
 @section pad
@@ -1652,7 +1945,7 @@ can be used to test the monowhite pixel format descriptor definition.
 
 @section scale
 
 
 @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 parameters @var{width} and @var{height} are expressions containing
 the following constants:
@@ -1700,6 +1993,17 @@ ratio of the input image.
 
 The default value of @var{width} and @var{height} is 0.
 
 
 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.
 Some examples follow:
 @example
 # scale the input video to a size of 200x100.
@@ -2026,11 +2330,11 @@ the @code{av_get_picture_type_char} function defined in
 @file{libavutil/avutil.h}.
 
 @item checksum
 @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
 
 @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
 @end table
 
 @section slicify
@@ -2039,7 +2343,7 @@ Pass the images of input video on to next video filter as multiple
 slices.
 
 @example
 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
 @end example
 
 The filter accepts the slice height as parameter. If the parameter is
@@ -2151,7 +2455,7 @@ unsharp=7:7:2.5
 unsharp=7:7:-2:7:7:-2
 
 # Use the default values with @command{ffmpeg}
 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
 @end example
 
 @section vflip
@@ -2159,7 +2463,7 @@ unsharp=7:7:-2:7:7:-2
 Flip the input video vertically.
 
 @example
 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
 @end example
 
 @section yadif
@@ -2230,7 +2534,7 @@ through the interface defined in @file{libavfilter/vsrc_buffer.h}.
 It accepts the following parameters:
 @var{width}:@var{height}:@var{pix_fmt_string}:@var{timebase_num}:@var{timebase_den}:@var{sample_aspect_ratio_num}:@var{sample_aspect_ratio.den}:@var{scale_params}
 
 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.
 defined.
 
 Follows the list of the accepted parameters.
@@ -2425,22 +2729,6 @@ testsrc=t=dc_luma
 
 will generate a "dc_luma" test pattern.
 
 
 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.
 @section frei0r_src
 
 Provide a frei0r source.
@@ -2468,7 +2756,11 @@ Some examples follow:
 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
 @end example
 
 frei0r_src=200x200:10:partik0l=1234 [overlay]; [in][overlay] overlay
 @end example
 
-@section rgbtestsrc, testsrc
+@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
 
 The @code{rgbtestsrc} source generates an RGB test pattern useful for
 detecting RGB vs BGR issues. You should see a red, green and blue
@@ -2478,7 +2770,7 @@ The @code{testsrc} source generates a test video pattern, showing a
 color pattern, a scrolling gradient and a timestamp. This is mainly
 intended for testing purposes.
 
 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
 separated by ":". The description of the accepted options follows.
 
 @table @option
@@ -2518,6 +2810,13 @@ testsrc=duration=5.3:size=qcif:rate=10
 will generate a video with a duration of 5.3 seconds, with size
 176x144 and a framerate of 10 frames per second.
 
 will generate a video with a duration of 5.3 seconds, with size
 176x144 and a framerate 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
 
 @chapter Video Sinks
 @c man end VIDEO SOURCES
 
 @chapter Video Sinks