X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Ffilters.texi;h=a4d828e04c76050ba47ab208f6edf9042de938b4;hb=b01891a9f08b9d271d75d179b3138242a958ee04;hp=0b5d898394cfd57a2797ca4341a5f0684d080505;hpb=33be39efe31326dc787efc54f5077e4c4b97896c;p=ffmpeg

diff --git a/doc/filters.texi b/doc/filters.texi
index 0b5d898394c..a4d828e04c7 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -641,6 +641,92 @@ Force the output to either unsigned 8-bit or signed 16-bit stereo
 aformat=sample_fmts=u8|s16:channel_layouts=stereo
 @end example
 
+@section agate
+
+A gate is mainly used to reduce lower parts of a signal. This kind of signal
+processing reduces disturbing noise between useful signals.
+
+Gating is done by detecting the volume below a chosen level @var{threshold}
+and divide it by the factor set with @var{ratio}. The bottom of the noise
+floor is set via @var{range}. Because an exact manipulation of the signal
+would cause distortion of the waveform the reduction can be levelled over
+time. This is done by setting @var{attack} and @var{release}.
+
+@var{attack} determines how long the signal has to fall below the threshold
+before any reduction will occur and @var{release} sets the time the signal
+has to raise above the threshold to reduce the reduction again.
+Shorter signals than the chosen attack time will be left untouched.
+
+@table @option
+@item level_in
+Set input level before filtering.
+
+@item range
+Set the level of gain reduction when the signal is below the threshold.
+
+@item threshold
+If a signal rises above this level the gain reduction is released.
+
+@item ratio
+Set a ratio about which the signal is reduced.
+
+@item attack
+Amount of milliseconds the signal has to rise above the threshold before gain
+reduction stops.
+
+@item release
+Amount of milliseconds the signal has to fall below the threshold before the
+reduction is increased again.
+
+@item makeup
+Set amount of amplification of signal after processing.
+
+@item knee
+Curve the sharp knee around the threshold to enter gain reduction more softly.
+
+@item detection
+Choose if exact signal should be taken for detection or an RMS like one.
+
+@item link
+Choose if the average level between all channels or the louder channel affects
+the reduction.
+@end table
+
+@section alimiter
+
+The limiter prevents input signal from raising over a desired threshold.
+This limiter uses lookahead technology to prevent your signal from distorting.
+It means that there is a small delay after signal is processed. Keep in mind
+that the delay it produces is the attack time you set.
+
+The filter accepts the following options:
+
+@table @option
+@item limit
+Don't let signals above this level pass the limiter. The removed amplitude is
+added automatically. Default is 1.
+
+@item attack
+The limiter will reach its attenuation level in this amount of time in
+milliseconds. Default is 5 milliseconds.
+
+@item release
+Come back from limiting to attenuation 1.0 in this amount of milliseconds.
+Default is 50 milliseconds.
+
+@item asc
+When gain reduction is always needed ASC takes care of releasing to an
+average reduction level rather than reaching a reduction of 0 in the release
+time.
+
+@item asc_level
+Select how much the release time is affected by ASC, 0 means nearly no changes
+in release time while 1 produces higher release times.
+@end table
+
+Depending on picked setting it is recommended to upsample input 2x or 4x times
+with @ref{aresample} before applying this filter.
+
 @section allpass
 
 Apply a two-pole all-pass filter with central frequency (in Hz)
@@ -1970,6 +2056,9 @@ threshold or gain).
 Controls need to be defined using the following syntax:
 c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
 @var{valuei} is the value set on the @var{i}-th control.
+Alternatively they can be also defined using the following syntax:
+@var{value0}|@var{value1}|@var{value2}|..., where
+@var{valuei} is the value set on the @var{i}-th control.
 If @option{controls} is set to @code{help}, all available controls and
 their valid ranges are printed.
 
@@ -2041,6 +2130,20 @@ Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
 @example
 ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
 @end example
+
+@item
+Increase volume by 20dB using fast lookahead limiter from Steve Harris
+@code{SWH Plugins} collection:
+@example
+ladspa=fast_lookahead_limiter_1913:fastLookaheadLimiter:20|0|2
+@end example
+
+@item
+Attenuate low frequencies using Multiband EQ from Steve Harris
+@code{SWH Plugins} collection:
+@example
+ladspa=mbeq_1197:mbeq:-24|-24|-24|0|0|0|0|0|0|0|0|0|0|0|0
+@end example
 @end itemize
 
 @subsection Commands
@@ -2189,6 +2292,87 @@ At end of filtering it displays @code{track_gain} and @code{track_peak}.
 Convert the audio sample format, sample rate and channel layout. It is
 not meant to be used directly.
 
+@section rubberband
+Apply time-stretching and pitch-shifting with librubberband.
+
+The filter accepts the following options:
+
+@table @option
+@item tempo
+Set tempo scale factor.
+
+@item pitch
+Set pitch scale factor.
+
+@item transients
+Set transients detector.
+Possible values are:
+@table @var
+@item crisp
+@item mixed
+@item smooth
+@end table
+
+@item detector
+Set detector.
+Possible values are:
+@table @var
+@item compound
+@item percussive
+@item soft
+@end table
+
+@item phase
+Set phase.
+Possible values are:
+@table @var
+@item laminar
+@item independent
+@end table
+
+@item window
+Set processing window size.
+Possible values are:
+@table @var
+@item standard
+@item short
+@item long
+@end table
+
+@item smoothing
+Set smoothing.
+Possible values are:
+@table @var
+@item off
+@item on
+@end table
+
+@item formant
+Enable formant preservation when shift pitching.
+Possible values are:
+@table @var
+@item shifted
+@item preserved
+@end table
+
+@item pitchq
+Set pitch quality.
+Possible values are:
+@table @var
+@item quality
+@item speed
+@item consistency
+@end table
+
+@item channels
+Set channels.
+Possible values are:
+@table @var
+@item apart
+@item together
+@end table
+@end table
+
 @section sidechaincompress
 
 This filter acts like normal compressor but has the ability to compress
@@ -2356,6 +2540,130 @@ silenceremove=1:5:0.02
 @end example
 @end itemize
 
+@section stereotools
+
+This filter has some handy utilities to manage stereo signals, for converting
+M/S stereo recordings to L/R signal while having control over the parameters
+or spreading the stereo image of master track.
+
+The filter accepts the following options:
+
+@table @option
+@item level_in
+Set input level before filtering for both channels. Defaults is 1.
+Allowed range is from 0.015625 to 64.
+
+@item level_out
+Set output level after filtering for both channels. Defaults is 1.
+Allowed range is from 0.015625 to 64.
+
+@item balance_in
+Set input balance between both channels. Default is 0.
+Allowed range is from -1 to 1.
+
+@item balance_out
+Set output balance between both channels. Default is 0.
+Allowed range is from -1 to 1.
+
+@item softclip
+Enable softclipping. Results in analog distortion instead of harsh digital 0dB
+clipping. Disabled by default.
+
+@item mutel
+Mute the left channel. Disabled by default.
+
+@item muter
+Mute the right channel. Disabled by default.
+
+@item phasel
+Change the phase of the left channel. Disabled by default.
+
+@item phaser
+Change the phase of the right channel. Disabled by default.
+
+@item mode
+Set stereo mode. Available values are:
+
+@table @samp
+@item lr>lr
+Left/Right to Left/Right, this is default.
+
+@item lr>ms
+Left/Right to Mid/Side.
+
+@item ms>lr
+Mid/Side to Left/Right.
+
+@item lr>ll
+Left/Right to Left/Left.
+
+@item lr>rr
+Left/Right to Right/Right.
+
+@item lr>l+r
+Left/Right to Left + Right.
+
+@item lr>rl
+Left/Right to Right/Left.
+@end table
+
+@item slev
+Set level of side signal. Default is 1.
+Allowed range is from 0.015625 to 64.
+
+@item sbal
+Set balance of side signal. Default is 0.
+Allowed range is from -1 to 1.
+
+@item mlev
+Set level of the middle signal. Default is 1.
+Allowed range is from 0.015625 to 64.
+
+@item mpan
+Set middle signal pan. Default is 0. Allowed range is from -1 to 1.
+
+@item base
+Set stereo base between mono and inversed channels. Default is 0.
+Allowed range is from -1 to 1.
+
+@item delay
+Set delay in milliseconds how much to delay left from right channel and
+vice versa. Default is 0. Allowed range is from -20 to 20.
+
+@item sclevel
+Set S/C level. Default is 1. Allowed range is from 1 to 100.
+
+@item phase
+Set the stereo phase in degrees. Default is 0. Allowed range is from 0 to 360.
+@end table
+
+@section stereowiden
+
+This filter enhance the stereo effect by suppressing signal common to both
+channels and by delaying the signal of left into right and vice versa,
+thereby widening the stereo effect.
+
+The filter accepts the following options:
+
+@table @option
+@item delay
+Time in milliseconds of the delay of left signal into right and vice versa.
+Default is 20 milliseconds.
+
+@item feedback
+Amount of gain in delayed signal into right and vice versa. Gives a delay
+effect of left signal in right output and vice versa which gives widening
+effect. Default is 0.3.
+
+@item crossfeed
+Cross feed of left into right with inverted phase. This helps in suppressing
+the mono. If the value is 1 it will cancel all the signal common to both
+channels. Default is 0.3.
+
+@item drymix
+Set level of input signal of original channel. Default is 0.8.
+@end table
+
 @section treble
 
 Boost or cut treble (upper) frequencies of the audio using a two-pole
@@ -2392,6 +2700,25 @@ slope
 Determine how steep is the filter's shelf transition.
 @end table
 
+@section tremolo
+
+Sinusoidal amplitude modulation.
+
+The filter accepts the following options:
+
+@table @option
+@item f
+Modulation frequency in Hertz. Modulation frequencies in the subharmonic range
+(20 Hz or lower) will result in a tremolo effect.
+This filter may also be used as a ring modulator by specifying
+a modulation frequency higher than 20 Hz.
+Range is 0.1 - 20000.0. Default value is 5.0 Hz.
+
+@item d
+Depth of modulation as a percentage. Range is 0.0 - 1.0.
+Default value is 0.5.
+@end table
+
 @section volume
 
 Adjust the input audio volume.
@@ -3166,6 +3493,7 @@ of @var{all_mode}. Default value is @code{normal}.
 Available values for component modes are:
 @table @samp
 @item addition
+@item addition128
 @item and
 @item average
 @item burn
@@ -3380,6 +3708,51 @@ boxblur=luma_radius=min(h\,w)/10:luma_power=1:chroma_radius=min(cw\,ch)/10:chrom
 @end example
 @end itemize
 
+@section chromakey
+YUV colorspace color/chroma keying.
+
+The filter accepts the following options:
+
+@table @option
+@item color
+The color which will be replaced with transparency.
+
+@item similarity
+Similarity percentage with the key color.
+
+0.01 matches only the exact key color, while 1.0 matches everything.
+
+@item blend
+Blend percentage.
+
+0.0 makes pixels either fully transparent, or not transparent at all.
+
+Higher values result in semi-transparent pixels, with a higher transparency
+the more similar the pixels color is to the key color.
+
+@item yuv
+Signals that the color passed is already in YUV instead of RGB.
+
+Litteral colors like "green" or "red" don't make sense with this enabled anymore.
+This can be used to pass exact YUV values as hexadecimal numbers.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Make every green pixel in the input image transparent:
+@example
+ffmpeg -i input.png -vf chromakey=green out.png
+@end example
+
+@item
+Overlay a greenscreen-video on top of a static black background.
+@example
+ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_complex "[1:v]chromakey=0x70de77:0.1:0.2[ckout];[0:v][ckout]overlay[out]" -map "[out]" output.mkv
+@end example
+@end itemize
+
 @section codecview
 
 Visualize information exported by some codecs.
@@ -5133,7 +5506,7 @@ The filter accepts the following options:
 @table @option
 @item contrast
 Set the contrast expression. The value must be a float value in range
-@code{-2.0} to @code{2.0}. The default value is "0".
+@code{-2.0} to @code{2.0}. The default value is "1".
 
 @item brightness
 Set the brightness expression. The value must be a float value in
@@ -7252,6 +7625,69 @@ lutyuv=y='bitand(val, 128+64+32)'
 @end example
 @end itemize
 
+@section maskedmerge
+
+Merge the first input stream with the second input stream using per pixel
+weights in the third input stream.
+
+A value of 0 in the third stream pixel component means that pixel component
+from first stream is returned unchanged, while maximum value (eg. 255 for
+8-bit videos) means that pixel component from second stream is returned
+unchanged. Intermediate values define the amount of merging between both
+input stream's pixel components.
+
+This filter accepts the following options:
+@table @option
+@item planes
+Set which planes will be processed as bitmap, unprocessed planes will be
+copied from first stream.
+By default value 0xf, all planes will be processed.
+@end table
+
+@section mcdeint
+
+Apply motion-compensation deinterlacing.
+
+It needs one field per frame as input and must thus be used together
+with yadif=1/3 or equivalent.
+
+This filter accepts the following options:
+@table @option
+@item mode
+Set the deinterlacing mode.
+
+It accepts one of the following values:
+@table @samp
+@item fast
+@item medium
+@item slow
+use iterative motion estimation
+@item extra_slow
+like @samp{slow}, but use multiple reference frames.
+@end table
+Default value is @samp{fast}.
+
+@item parity
+Set the picture field parity assumed for the input video. It must be
+one of the following values:
+
+@table @samp
+@item 0, tff
+assume top field first
+@item 1, bff
+assume bottom field first
+@end table
+
+Default value is @samp{bff}.
+
+@item qp
+Set per-block quantization parameter (QP) used by the internal
+encoder.
+
+Higher values should result in a smoother motion vector field but less
+optimal individual vectors. Default value is 1.
+@end table
+
 @section mergeplanes
 
 Merge color channel components from several video streams.
@@ -7311,50 +7747,6 @@ format=rgb24,mergeplanes=0x000102:yuv444p
 @end example
 @end itemize
 
-@section mcdeint
-
-Apply motion-compensation deinterlacing.
-
-It needs one field per frame as input and must thus be used together
-with yadif=1/3 or equivalent.
-
-This filter accepts the following options:
-@table @option
-@item mode
-Set the deinterlacing mode.
-
-It accepts one of the following values:
-@table @samp
-@item fast
-@item medium
-@item slow
-use iterative motion estimation
-@item extra_slow
-like @samp{slow}, but use multiple reference frames.
-@end table
-Default value is @samp{fast}.
-
-@item parity
-Set the picture field parity assumed for the input video. It must be
-one of the following values:
-
-@table @samp
-@item 0, tff
-assume top field first
-@item 1, bff
-assume bottom field first
-@end table
-
-Default value is @samp{bff}.
-
-@item qp
-Set per-block quantization parameter (QP) used by the internal
-encoder.
-
-Higher values should result in a smoother motion vector field but less
-optimal individual vectors. Default value is 1.
-@end table
-
 @section mpdecimate
 
 Drop frames that do not differ greatly from the previous frame in
@@ -7485,6 +7877,30 @@ noise=alls=20:allf=t+u
 
 Pass the video source unchanged to the output.
 
+@section ocr
+Optical Character Recognition
+
+This filter uses Tesseract for optical character recognition.
+
+It accepts the following options:
+
+@table @option
+@item datapath
+Set datapath to tesseract data. Default is to use whatever was
+set at installation.
+
+@item language
+Set language, default is "eng".
+
+@item whitelist
+Set character whitelist.
+
+@item blacklist
+Set character blacklist.
+@end table
+
+The filter exports recognized text as the frame metadata @code{lavfi.ocr.text}.
+
 @section ocv
 
 Apply a video transform using libopencv.
@@ -13107,6 +13523,8 @@ It accepts the following values:
 @item bhann
 @item sine
 @item nuttall
+@item lanczos
+@item gauss
 @end table
 Default is @code{hanning}.
 
@@ -13118,7 +13536,7 @@ which means optimal overlap for selected window function will be picked.
 Set time averaging. Setting this to 0 will display current maximal peaks.
 Default is @code{1}, which means time averaging is disabled.
 
-@item color
+@item colors
 Specify list of colors separated by space or by '|' which will be used to
 draw channel frequencies. Unrecognized or missing colors will be replaced
 by white color.