Merge commit '90adbf4abf336f8042aecdf1e18fdf76a96304b1'
[ffmpeg.git] / doc / filters.texi
index c99a384..0ef6f56 100644 (file)
@@ -431,7 +431,7 @@ Range is between 0 and 1.
 @end table
 
 @section acontrast
-Simple audio dynamic range commpression/expansion filter.
+Simple audio dynamic range compression/expansion filter.
 
 The filter accepts the following options:
 
@@ -605,8 +605,8 @@ The lower value, the more samples will be detected as impulsive noise.
 @item b
 Set burst fusion, in percentage of window size. Allowed range is @code{0} to
 @code{10}. Default value is @code{2}.
-If any two samples deteced as noise are spaced less than this value then any
-sample inbetween those two samples will be also detected as noise.
+If any two samples detected as noise are spaced less than this value then any
+sample between those two samples will be also detected as noise.
 
 @item m
 Set overlap method.
@@ -683,6 +683,7 @@ Set list of delays in milliseconds for each channel separated by '|'.
 Unused delays will be silently ignored. If number of given delays is
 smaller than number of channels all remaining channels will not be delayed.
 If you want to delay exact number of samples, append 'S' to number.
+If you want instead to delay in seconds, append 's' to number.
 @end table
 
 @subsection Examples
@@ -957,6 +958,8 @@ select double-exponential seat
 select double-exponential sigmoid
 @item losi
 select logistic sigmoid
+@item nofade
+no fade applied
 @end table
 @end table
 
@@ -1072,17 +1075,17 @@ Apply arbitrary expressions to samples in frequency domain.
 @table @option
 @item real
 Set frequency domain real expression for each separate channel separated
-by '|'. Default is "1".
+by '|'. Default is "re".
 If the number of input channels is greater than the number of
 expressions, the last specified expression is used for the remaining
 output channels.
 
 @item imag
 Set frequency domain imaginary expression for each separate channel
-separated by '|'. If not set, @var{real} option is used.
+separated by '|'. Default is "im".
 
 Each expression in @var{real} and @var{imag} can contain the following
-constants:
+constants and functions:
 
 @table @option
 @item sr
@@ -1102,6 +1105,18 @@ number of channels
 
 @item pts
 current frame pts
+
+@item re
+current real part of frequency bin of current channel
+
+@item im
+current imaginary part of frequency bin of current channel
+
+@item real(b, ch)
+Return the value of real part of frequency bin at location (@var{bin},@var{channel})
+
+@item imag(b, ch)
+Return the value of imaginary part of frequency bin at location (@var{bin},@var{channel})
 @end table
 
 @item win_size
@@ -1139,7 +1154,7 @@ window function will be picked. Default is @code{0.75}.
 @item
 Leave almost only low frequencies in audio:
 @example
-afftfilt="1-clip((b/nb)*b,0,1)"
+afftfilt="'real=re * (1-clip((b/nb)*b,0,1))':imag='im * (1-clip((b/nb)*b,0,1))'"
 @end example
 @end itemize
 
@@ -1153,7 +1168,7 @@ up to 60 seconds long.
 
 It can be used as component for digital crossover filters,
 room equalization, cross talk cancellation, wavefield synthesis,
-auralization, ambiophonics and ambisonics.
+auralization, ambiophonics, ambisonics and spatialization.
 
 This filter uses second stream as FIR coefficients.
 If second stream holds single channel, it will be used
@@ -1205,7 +1220,7 @@ Set max allowed Impulse Response filter duration in seconds. Default is 30 secon
 Allowed range is 0.1 to 60 seconds.
 
 @item response
-Show IR frequency reponse, magnitude(magenta) and phase(green) and group delay(yellow) in additional video stream.
+Show IR frequency response, magnitude(magenta), phase(green) and group delay(yellow) in additional video stream.
 By default it is disabled.
 
 @item channel
@@ -1217,6 +1232,16 @@ Set video stream size. This option is used only when @var{response} is enabled.
 
 @item rate
 Set video stream frame rate. This option is used only when @var{response} is enabled.
+
+@item minp
+Set minimal partition size used for convolution. Default is @var{8192}.
+Allowed range is from @var{8} to @var{32768}.
+Lower values decreases latency at cost of higher CPU usage.
+
+@item maxp
+Set maximal partition size used for convolution. Default is @var{8192}.
+Allowed range is from @var{8} to @var{32768}.
+Lower values may increase CPU usage.
 @end table
 
 @subsection Examples
@@ -1357,7 +1382,7 @@ Z-plane zeros/poles, polar degrees
 
 @item r
 Set kind of processing.
-Can be @code{d} - direct or @code{s} - serial cascading. Defauls is @code{s}.
+Can be @code{d} - direct or @code{s} - serial cascading. Default is @code{s}.
 
 @item e
 Set filtering precision.
@@ -1374,7 +1399,7 @@ single-precision floating-point
 @end table
 
 @item response
-Show IR frequency reponse, magnitude and phase in additional video stream.
+Show IR frequency response, magnitude and phase in additional video stream.
 By default it is disabled.
 
 @item channel
@@ -1400,7 +1425,7 @@ used for all remaining channels.
 
 @itemize
 @item
-Apply 2 pole elliptic notch at arround 5000Hz for 48000 Hz sample rate:
+Apply 2 pole elliptic notch at around 5000Hz for 48000 Hz sample rate:
 @example
 aiir=k=1:z=7.957584807809675810E-1 -2.575128568908332300 3.674839853930788710 -2.57512875289799137 7.957586296317130880E-1:p=1 -2.86950072432325953 3.63022088054647218 -2.28075678147272232 6.361362326477423500E-1:f=tf:r=d
 @end example
@@ -1727,6 +1752,29 @@ Full filter invocation with asendcmd may look like this:
 asendcmd=c='4.0 anequalizer change 0|f=200|w=50|g=1',anequalizer=...
 @end table
 
+@section anlmdn
+
+Reduce broadband noise in audio samples using Non-Local Means algorithm.
+
+Each sample is adjusted by looking for other samples with similar contexts. This
+context similarity is defined by comparing their surrounding patches of size
+@option{p}. Patches are searched in an area of @option{r} around the sample.
+
+The filter accepts the following options.
+
+@table @option
+@item s
+Set denoising strength. Allowed range is from 0.00001 to 10. Default value is 0.00001.
+
+@item p
+Set patch radius duration. Allowed range is from 1 to 100 milliseconds.
+Default value is 2 milliseconds.
+
+@item r
+Set research radius duration. Allowed range is from 2 to 300 milliseconds.
+Default value is 6 milliseconds.
+@end table
+
 @section anull
 
 Pass the audio source unchanged to the output.
@@ -1754,11 +1802,23 @@ Set the minimum total number of samples in the output audio stream. If
 the value is longer than the input audio length, silence is added to
 the end, until the value is reached. This option is mutually exclusive
 with @option{pad_len}.
+
+@item pad_dur
+Specify the duration of samples of silence to add. See
+@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
+for the accepted syntax. Used only if set to non-zero value.
+
+@item whole_dur
+Specify the minimum total duration in the output audio stream. See
+@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
+for the accepted syntax. Used only if set to non-zero value. If the value is longer than
+the input audio length, silence is added to the end, until the value is reached.
+This option is mutually exclusive with @option{pad_dur}
 @end table
 
-If neither the @option{pad_len} nor the @option{whole_len} option is
-set, the filter will add silence to the end of the input stream
-indefinitely.
+If neither the @option{pad_len} nor the @option{whole_len} nor @option{pad_dur}
+nor @option{whole_dur} option is set, the filter will add silence to the end of
+the input stream indefinitely.
 
 @subsection Examples
 
@@ -3496,7 +3556,8 @@ Full example using wav files as coefficients with amovie filters for 7.1 downmix
 each amovie filter use stereo file with IR coefficients as input.
 The files give coefficients for each position of virtual loudspeaker:
 @example
-ffmpeg -i input.wav -lavfi-complex "amovie=azi_270_ele_0_DFC.wav[sr],amovie=azi_90_ele_0_DFC.wav[sl],amovie=azi_225_ele_0_DFC.wav[br],amovie=azi_135_ele_0_DFC.wav[bl],amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe],amovie=azi_35_ele_0_DFC.wav[fl],amovie=azi_325_ele_0_DFC.wav[fr],[a:0][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
+ffmpeg -i input.wav
+-filter_complex "amovie=azi_270_ele_0_DFC.wav[sr];amovie=azi_90_ele_0_DFC.wav[sl];amovie=azi_225_ele_0_DFC.wav[br];amovie=azi_135_ele_0_DFC.wav[bl];amovie=azi_0_ele_0_DFC.wav,asplit[fc][lfe];amovie=azi_35_ele_0_DFC.wav[fl];amovie=azi_325_ele_0_DFC.wav[fr];[0:a][fl][fr][fc][lfe][bl][br][sl][sr]headphone=FL|FR|FC|LFE|BL|BR|SL|SR"
 output.wav
 @end example
 
@@ -3504,7 +3565,7 @@ output.wav
 Full example using wav files as coefficients with amovie filters for 7.1 downmix,
 but now in @var{multich} @var{hrir} format.
 @example
-ffmpeg -i input.wav -lavfi-complex "amovie=minp.wav[hrirs],[a:0][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
+ffmpeg -i input.wav -filter_complex "amovie=minp.wav[hrirs];[0:a][hrirs]headphone=map=FL|FR|FC|LFE|BL|BR|SL|SR:hrir=multich"
 output.wav
 @end example
 @end itemize
@@ -4472,6 +4533,28 @@ Descriptions with unrecognised channel names are ignored.
 
 @item lfegain
 Set custom gain for LFE channels. Value is in dB. Default is 0.
+
+@item framesize
+Set custom frame size in number of samples. Default is 1024.
+Allowed range is from 1024 to 96000. Only used if option @samp{type}
+is set to @var{freq}.
+
+@item normalize
+Should all IRs be normalized upon importing SOFA file.
+By default is enabled.
+
+@item interpolate
+Should nearest IRs be interpolated with neighbor IRs if exact position
+does not match. By default is disabled.
+
+@item minphase
+Minphase all IRs upon loading of SOFA file. By default is disabled.
+
+@item anglestep
+Set neighbor search angle step. Only used if option @var{interpolate} is enabled.
+
+@item radstep
+Set neighbor search radius step. Only used if option @var{interpolate} is enabled.
 @end table
 
 @subsection Examples
@@ -5565,7 +5648,7 @@ For example radius of 3 will instruct filter to calculate average of 7 frames.
 Set factor to amplify difference. Default is 2. Allowed range is from 0 to 65535.
 
 @item threshold
-Set threshold for difference amplification. Any differrence greater or equal to
+Set threshold for difference amplification. Any difference greater or equal to
 this value will not alter source pixel. Default is 10.
 Allowed range is from 0 to 65535.
 
@@ -5950,7 +6033,7 @@ The filter accepts the following options.
 @item sigma
 Set denoising strength. Default value is 1.
 Allowed range is from 0 to 999.9.
-The denoising algorith is very sensitive to sigma, so adjust it
+The denoising algorithm is very sensitive to sigma, so adjust it
 according to the source.
 
 @item block
@@ -6231,6 +6314,23 @@ ffmpeg -f lavfi -i color=c=black:s=1280x720 -i video.mp4 -shortest -filter_compl
 @end example
 @end itemize
 
+@section chromashift
+Shift chroma pixels horizontally and/or vertically.
+
+The filter accepts the following options:
+@table @option
+@item cbh
+Set amount to shift chroma-blue horizontally.
+@item cbv
+Set amount to shift chroma-blue vertically.
+@item crh
+Set amount to shift chroma-red horizontally.
+@item crv
+Set amount to shift chroma-red vertically.
+@item edge
+Set edge mode, can be @var{smear}, default, or @var{warp}.
+@end table
+
 @section ciescope
 
 Display CIE color diagram with pixels overlaid onto it.
@@ -7739,6 +7839,30 @@ had noise.
 
 The @code{deconvolve} filter also supports the @ref{framesync} options.
 
+@section dedot
+
+Reduce cross-luminance (dot-crawl) and cross-color (rainbows) from video.
+
+It accepts the following options:
+
+@table @option
+@item m
+Set mode of operation. Can be combination of @var{dotcrawl} for cross-luminance reduction and/or
+@var{rainbows} for cross-color reduction.
+
+@item lt
+Set spatial luma threshold. Lower values increases reduction of cross-luminance.
+
+@item tl
+Set tolerance for temporal luma. Higher values increases reduction of cross-luminance.
+
+@item tc
+Set tolerance for chroma temporal variation. Higher values increases reduction of cross-color.
+
+@item ct
+Set temporal chroma threshold. Lower values increases reduction of cross-color.
+@end table
+
 @section deflate
 
 Apply deflate effect to the video.
@@ -10006,6 +10130,35 @@ Select frame after every @code{step} frames.
 Allowed values are positive integers higher than 0. Default value is @code{1}.
 @end table
 
+@section freezedetect
+
+Detect frozen video.
+
+This filter logs a message and sets frame metadata when it detects that the
+input video has no significant change in content during a specified duration.
+Video freeze detection calculates the mean average absolute difference of all
+the components of video frames and compares it to a noise floor.
+
+The printed times and duration are expressed in seconds. The
+@code{lavfi.freezedetect.freeze_start} metadata key is set on the first frame
+whose timestamp equals or exceeds the detection duration and it contains the
+timestamp of the first frame of the freeze. The
+@code{lavfi.freezedetect.freeze_duration} and
+@code{lavfi.freezedetect.freeze_end} metadata keys are set on the first frame
+after the freeze.
+
+The filter accepts the following options:
+
+@table @option
+@item noise, n
+Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
+specified value) or as a difference ratio between 0 and 1. Default is -60dB, or
+0.001.
+
+@item duration, d
+Set freeze duration until notification (default is 2 seconds).
+@end table
+
 @anchor{frei0r}
 @section frei0r
 
@@ -10112,7 +10265,7 @@ The filter accepts the following options:
 Set horizontal sigma, standard deviation of Gaussian blur. Default is @code{0.5}.
 
 @item steps
-Set number of steps for Gaussian approximation. Defauls is @code{1}.
+Set number of steps for Gaussian approximation. Default is @code{1}.
 
 @item planes
 Set which planes to filter. By default all planes are filtered.
@@ -10381,7 +10534,7 @@ max value instead of calculating Minkowski distance.
 @item sigma
 The standard deviation of Gaussian blur to be applied on the scene. Must be
 chosen in the range [0,1024.0] and default value = 1. floor( @var{sigma} * break_off_sigma(3) )
-can't be euqal to 0 if @var{difford} is greater than 0.
+can't be equal to 0 if @var{difford} is greater than 0.
 @end table
 
 @subsection Examples
@@ -11307,7 +11460,9 @@ Set the file path to be used to store logs.
 Set the format of the log file (xml or json).
 
 @item enable_transform
-Enables transform for computing vmaf.
+This option can enable/disable the @code{score_transform} applied to the final predicted VMAF score,
+if you have specified score_transform option in the input parameter file passed to @code{run_vmaf_training.py}
+Default value: @code{false}
 
 @item phone_model
 Invokes the phone model which will generate VMAF scores higher than in the
@@ -11346,7 +11501,7 @@ ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf -f null -
 
 Example with options:
 @example
-ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:enable-transform=1" -f null -
+ffmpeg -i main.mpg -i ref.mpg -lavfi libvmaf="psnr=1:log_fmt=json" -f null -
 @end example
 
 @section limiter
@@ -11432,8 +11587,12 @@ Available values are:
 Use values from the nearest defined point.
 @item linear
 Interpolate values using the linear interpolation.
+@item cosine
+Interpolate values using the cosine interpolation.
 @item cubic
 Interpolate values using the cubic interpolation.
+@item spline
+Interpolate values using the spline interpolation.
 @end table
 @end table
 
@@ -11662,6 +11821,10 @@ set second pixel component expression
 set third pixel component expression
 @item c3
 set fourth pixel component expression, corresponds to the alpha component
+
+@item d
+set output bit depth, only available for @code{lut2} filter. By default is 0,
+which means bit depth is automatically picked from first input format.
 @end table
 
 Each of them specifies the expression to use for computing the lookup table for
@@ -11754,6 +11917,33 @@ copied from first stream.
 By default value 0xf, all planes will be processed.
 @end table
 
+@section maskfun
+Create mask from input video.
+
+For example it is useful to create motion masks after @code{tblend} filter.
+
+This filter accepts the following options:
+
+@table @option
+@item low
+Set low threshold. Any pixel component lower or exact than this value will be set to 0.
+
+@item high
+Set high threshold. Any pixel component higher than this value will be set to max value
+allowed for current pixel format.
+
+@item planes
+Set planes to filter, by default all available planes are filtered.
+
+@item fill
+Fill all frame pixels with this value.
+
+@item sum
+Set max average pixel value for frame. If sum of all pixel components is higher that this
+average, output frame will be completely filled with value set by @var{fill} option.
+Typically useful for scene changes when used in combination with @code{tblend} filter.
+@end table
+
 @section mcdeint
 
 Apply motion-compensation deinterlacing.
@@ -12107,10 +12297,10 @@ The filter accepts the following options.
 
 @table @option
 @item s
-Set denoising strength.
+Set denoising strength. Default is 1.0. Must be in range [1.0, 30.0].
 
 @item p
-Set patch size.
+Set patch size. Default is 7. Must be odd number in range [0, 99].
 
 @item pc
 Same as @option{p} but for chroma planes.
@@ -12118,7 +12308,7 @@ Same as @option{p} but for chroma planes.
 The default value is @var{0} and means automatic.
 
 @item r
-Set research size.
+Set research size. Default is 15. Must be odd number in range [0, 99].
 
 @item rc
 Same as @option{r} but for chroma planes.
@@ -14240,6 +14430,31 @@ trim=end=5,reverse
 @end example
 @end itemize
 
+@section rgbashift
+Shift R/G/B/A pixels horizontally and/or vertically.
+
+The filter accepts the following options:
+@table @option
+@item rh
+Set amount to shift red horizontally.
+@item rv
+Set amount to shift red vertically.
+@item gh
+Set amount to shift green horizontally.
+@item gv
+Set amount to shift green vertically.
+@item bh
+Set amount to shift blue horizontally.
+@item bv
+Set amount to shift blue vertically.
+@item ah
+Set amount to shift alpha horizontally.
+@item av
+Set amount to shift alpha vertically.
+@item edge
+Set edge mode, can be @var{smear}, default, or @var{warp}.
+@end table
+
 @section roberts
 Apply roberts cross operator to input video stream.
 
@@ -15121,7 +15336,7 @@ Keep the same color primaries property (default).
 @end table
 
 @item color_trc
-Set the color transfert.
+Set the color transfer.
 Available values are:
 
 @table @samp
@@ -15177,6 +15392,13 @@ Keep the same colorspace property (default).
 Show a line containing various information for each input video frame.
 The input video is not modified.
 
+This filter supports the following options:
+
+@table @option
+@item checksum
+Calculate checksums of each plane. By default enabled.
+@end table
+
 The shown line contains a sequence of key/value pairs of the form
 @var{key}:@var{value}.
 
@@ -18636,7 +18858,7 @@ Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
 @item 3rdiv
 Set multiplier for calculated value for each plane.
 If unset or 0, it will be sum of all matrix elements.
-The option value must be an float number greater or equal to @code{0.0}. Default value is @code{1.0}.
+The option value must be a float number greater or equal to @code{0.0}. Default value is @code{1.0}.
 
 @item 0bias
 @item 1bias
@@ -18644,7 +18866,7 @@ The option value must be an float number greater or equal to @code{0.0}. Default
 @item 3bias
 Set bias for each plane. This value is added to the result of the multiplication.
 Useful for making the overall image brighter or darker.
-The option value must be an float number greater or equal to @code{0.0}. Default value is @code{0.0}.
+The option value must be a float number greater or equal to @code{0.0}. Default value is @code{0.0}.
 
 @end table
 
@@ -18914,7 +19136,7 @@ the cpu version tonemap currently. A setting of 0.0 disables this option.
 
 @item threshold
 The tonemapping algorithm parameters is fine-tuned per each scene. And a threshold
-is used to detect whether the scene has changed or not. If the distance beween
+is used to detect whether the scene has changed or not. If the distance between
 the current frame average brightness and the current running average exceeds
 a threshold value, we would re-calculate scene average and peak brightness.
 The default value is 0.2.
@@ -19336,7 +19558,7 @@ Set outer coloring mode.
 It shall assume one of following values:
 @table @option
 @item iteration_count
-Set iteration cound mode.
+Set iteration count mode.
 @item normalized_iteration_count
 set normalized iteration count mode.
 @end table
@@ -19914,7 +20136,7 @@ Default is @code{log}.
 
 @item acount
 Set how much frames to accumulate in histogram.
-Defauls is 1. Setting this to -1 accumulates all frames.
+Default is 1. Setting this to -1 accumulates all frames.
 
 @item rheight
 Set histogram ratio of window height.
@@ -22257,7 +22479,7 @@ This filter is primarily created for reversing processed @ref{showspectrum}
 filter outputs, but can synthesize sound from other spectrograms too.
 But in such case results are going to be poor if the phase data is not
 available, because in such cases phase data need to be recreated, usually
-its just recreated from random noise.
+it's just recreated from random noise.
 For best results use gray only output (@code{channel} color mode in
 @ref{showspectrum} filter) and @code{log} scale for magnitude video and
 @code{lin} scale for phase video. To produce phase, for 2nd video, use