Merge commit '9d3ea5cbf57e30bf2717a9ce64e858dad8a02aa6'
[ffmpeg.git] / doc / filters.texi
index 35a0e71..eaee284 100644 (file)
@@ -733,6 +733,83 @@ afade=t=out:st=875:d=25
 @end example
 @end itemize
 
+@section afftfilt
+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".
+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.
+
+Each expression in @var{real} and @var{imag} can contain the following
+constants:
+
+@table @option
+@item sr
+sample rate
+
+@item b
+current frequency bin number
+
+@item nb
+number of available bins
+
+@item ch
+channel number of the current expression
+
+@item chs
+number of channels
+
+@item pts
+current frame pts
+@end table
+
+@item win_size
+Set window size.
+
+It accepts the following values:
+@table @samp
+@item w16
+@item w32
+@item w64
+@item w128
+@item w256
+@item w512
+@item w1024
+@item w2048
+@item w4096
+@item w8192
+@item w16384
+@item w32768
+@item w65536
+@end table
+Default is @code{w4096}
+
+@item win_func
+Set window function. Default is @code{hann}.
+
+@item overlap
+Set window overlap. If set to 1, the recommended overlap for selected
+window function will be picked. Default is @code{0.75}.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Leave almost only low frequencies in audio:
+@example
+afftfilt="1-clip((b/nb)*b,0,1)"
+@end example
+@end itemize
+
 @anchor{aformat}
 @section aformat
 
@@ -4585,6 +4662,68 @@ For example to convert from BT.601 to SMPTE-240M, use the command:
 colormatrix=bt601:smpte240m
 @end example
 
+@section convolution
+
+Apply convolution 3x3 or 5x5 filter.
+
+The filter accepts the following options:
+
+@table @option
+@item 0m
+@item 1m
+@item 2m
+@item 3m
+Set matrix for each plane.
+Matrix is sequence of 9 or 25 signed integers.
+
+@item 0rdiv
+@item 1rdiv
+@item 2rdiv
+@item 3rdiv
+Set multiplier for calculated value for each plane.
+
+@item 0bias
+@item 1bias
+@item 2bias
+@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. Default is 0.0.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Apply sharpen:
+@example
+convolution="0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0:0 -1 0 -1 5 -1 0 -1 0"
+@end example
+
+@item
+Apply blur:
+@example
+convolution="1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1 1 1 1 1 1 1 1 1:1/9:1/9:1/9:1/9"
+@end example
+
+@item
+Apply edge enhance:
+@example
+convolution="0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:0 0 0 -1 1 0 0 0 0:5:1:1:1:0:128:128:128"
+@end example
+
+@item
+Apply edge detect:
+@example
+convolution="0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:0 1 0 1 -4 1 0 1 0:5:5:5:1:0:128:128:128"
+@end example
+
+@item
+Apply emboss:
+@example
+convolution="-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2:-2 -1 0 -1 1 1 0 1 2"
+@end example
+@end itemize
+
 @section copy
 
 Copy the input source unchanged to the output. This is mainly useful for
@@ -6468,6 +6607,12 @@ Sharpen:
 fftfilt=dc_Y=0:weight_Y='1+squish(1-(Y+X)/100)'
 @end example
 
+@item
+Blur:
+@example
+fftfilt=dc_Y=0:weight_Y='exp(-4 * ((Y+X)/(W+H)))'
+@end example
+
 @end itemize
 
 @section field
@@ -9948,6 +10093,21 @@ dimension is divisible by n and adjust the value if necessary.
 See below for the list of accepted constants for use in the dimension
 expression.
 
+@item eval
+Specify when to evaluate @var{width} and @var{height} expression. It accepts the following values:
+
+@table @samp
+@item init
+Only evaluate expressions once during the filter initialization or when a command is processed.
+
+@item frame
+Evaluate expressions for each incoming frame.
+
+@end table
+
+Default value is @samp{init}.
+
+
 @item interl
 Set the interlacing mode. It accepts the following values:
 
@@ -9971,6 +10131,15 @@ Set libswscale scaling flags. See
 complete list of values. If not explicitly specified the filter applies
 the default flags.
 
+
+@item param0, param1
+Set libswscale input parameters for scaling algorithms that need them. See
+@ref{sws_params,,the ffmpeg-scaler manual,ffmpeg-scaler} for the
+complete documentation. If not explicitly specified the filter applies
+empty parameters.
+
+
+
 @item size, s
 Set the video size. For the syntax of this option, check the
 @ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
@@ -12413,6 +12582,9 @@ single input image.
 
 @item s
 Set the output image size, default is 'hd720'.
+
+@item fps
+Set the output frame rate, default is '25'.
 @end table
 
 Each expression can contain the following constants:
@@ -12612,6 +12784,63 @@ Possible value are:
 @end table
 
 Default is same as input.
+
+@item rangein, rin
+Set the input color range.
+
+Possible values are:
+@table @var
+@item input
+@item limited
+@item full
+@end table
+
+Default is same as input.
+
+@item primariesin, pin
+Set the input color primaries.
+
+Possible values are:
+@table @var
+@item input
+@item 709
+@item unspecified
+@item 170m
+@item 240m
+@item 2020
+@end table
+
+Default is same as input.
+
+@item transferin, tin
+Set the input transfer characteristics.
+
+Possible values are:
+@table @var
+@item input
+@item 709
+@item unspecified
+@item 601
+@item linear
+@item 2020_10
+@item 2020_12
+@end table
+
+Default is same as input.
+
+@item matrixin, min
+Set the input colorspace matrix.
+
+Possible value are:
+@table @var
+@item input
+@item 709
+@item unspecified
+@item 470bg
+@item 170m
+@item 2020_ncl
+@item 2020_cl
+@end table
 @end table
 
 The values of the @option{w} and @option{h} options are expressions
@@ -13282,6 +13511,84 @@ tools.
 
 Below is a description of the currently available multimedia filters.
 
+@section ahistogram
+
+Convert input audio to a video output, displaying the volume histogram.
+
+The filter accepts the following options:
+
+@table @option
+@item dmode
+Specify how histogram is calculated.
+
+It accepts the following values:
+@table @samp
+@item single
+Use single histogram for all channels.
+@item separate
+Use separate histogram for each channel.
+@end table
+Default is @code{single}.
+
+@item rate, r
+Set frame rate, expressed as number of frames per second. Default
+value is "25".
+
+@item size, s
+Specify the video size for the output. For the syntax of this option, check the
+@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
+Default value is @code{hd720}.
+
+@item scale
+Set display scale.
+
+It accepts the following values:
+@table @samp
+@item log
+logarithmic
+@item sqrt
+square root
+@item cbrt
+cubic root
+@item lin
+linear
+@item rlog
+reverse logarithmic
+@end table
+Default is @code{log}.
+
+@item ascale
+Set amplitude scale.
+
+It accepts the following values:
+@table @samp
+@item log
+logarithmic
+@item lin
+linear
+@end table
+Default is @code{log}.
+
+@item acount
+Set how much frames to accumulate in histogram.
+Defauls is 1. Setting this to -1 accumulates all frames.
+
+@item rheight
+Set histogram ratio of window height.
+
+@item slide
+Set sonogram sliding.
+
+It accepts the following values:
+@table @samp
+@item replace
+replace old rows with new ones.
+@item scroll
+scroll from top to bottom.
+@end table
+Default is @code{replace}.
+@end table
+
 @section aphasemeter
 
 Convert input audio to a video output, displaying the audio phase.
@@ -13372,6 +13679,20 @@ Allowed range is @code{[0, 255]}.
 
 @item zoom
 Set the zoom factor. Default value is @code{1}. Allowed range is @code{[1, 10]}.
+
+@item draw
+Set the vectorscope drawing mode.
+
+Available values are:
+@table @samp
+@item dot
+Draw dot for each sample.
+
+@item line
+Draw line between previous and current sample.
+@end table
+
+Default value is @samp{dot}.
 @end table
 
 @subsection Examples
@@ -14535,6 +14856,7 @@ It accepts the following values:
 @item nuttall
 @item lanczos
 @item gauss
+@item tukey
 @end table
 Default is @code{hanning}.
 
@@ -14563,6 +14885,7 @@ Default is @code{combined}.
 
 @end table
 
+@anchor{showspectrum}
 @section showspectrum
 
 Convert input audio to a video output, representing the audio frequency
@@ -14625,6 +14948,10 @@ each channel is displayed using the nebulae color scheme
 each channel is displayed using the fire color scheme
 @item fiery
 each channel is displayed using the fiery color scheme
+@item fruit
+each channel is displayed using the fruit color scheme
+@item cool
+each channel is displayed using the cool color scheme
 @end table
 
 Default value is @samp{channel}.
@@ -14676,6 +15003,7 @@ It accepts the following values:
 @item nuttall
 @item lanczos
 @item gauss
+@item tukey
 @end table
 
 Default value is @code{hann}.
@@ -14688,6 +15016,13 @@ Set orientation of time vs frequency axis. Can be @code{vertical} or
 Set ratio of overlap window. Default value is @code{0}.
 When value is @code{1} overlap is set to recommended size for specific
 window function currently used.
+
+@item gain
+Set scale gain for calculating intensity color values.
+Default value is @code{1}.
+
+@item data
+Set which data to display. Can be @code{magnitude}, default or @code{phase}.
 @end table
 
 The usage is very similar to the showwaves filter; see the examples in that
@@ -14754,6 +15089,10 @@ each channel is displayed using the nebulae color scheme
 each channel is displayed using the fire color scheme
 @item fiery
 each channel is displayed using the fiery color scheme
+@item fruit
+each channel is displayed using the fruit color scheme
+@item cool
+each channel is displayed using the cool color scheme
 @end table
 Default value is @samp{intensity}.
 
@@ -14803,12 +15142,20 @@ It accepts the following values:
 @item nuttall
 @item lanczos
 @item gauss
+@item tukey
 @end table
 Default value is @code{hann}.
 
 @item orientation
 Set orientation of time vs frequency axis. Can be @code{vertical} or
 @code{horizontal}. Default is @code{vertical}.
+
+@item gain
+Set scale gain for calculating intensity color values.
+Default value is @code{1}.
+
+@item legend
+Draw time and frequency axes and legends. Default is enabled.
 @end table
 
 @subsection Examples
@@ -14909,6 +15256,13 @@ option @var{n}. Default value is "25".
 @item split_channels
 Set if channels should be drawn separately or overlap. Default value is 0.
 
+@item colors
+Set colors separated by '|' which are going to be used for drawing of each channel.
+
+@item scale
+Set amplitude scale. Can be linear @code{lin} or logarithmic @code{log}.
+Default is linear.
+
 @end table
 
 @subsection Examples
@@ -14943,6 +15297,13 @@ Default value is @code{600x240}.
 
 @item split_channels
 Set if channels should be drawn separately or overlap. Default value is 0.
+
+@item colors
+Set colors separated by '|' which are going to be used for drawing of each channel.
+
+@item scale
+Set amplitude scale. Can be linear @code{lin} or logarithmic @code{log}.
+Default is linear.
 @end table
 
 @subsection Examples
@@ -14964,6 +15325,68 @@ ffmpeg -i audio.mp3 -filter_complex "showwavespic,colorchannelmixer=rr=66/255:gg
 @end example
 @end itemize
 
+@section spectrumsynth
+
+Sythesize audio from 2 input video spectrums, first input stream represents
+magnitude across time and second represents phase across time.
+The filter will transform from frequency domain as displayed in videos back
+to time domain as presented in audio output.
+
+This filter is primarly 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.
+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
+@code{data} option. Inputs videos should generally use @code{fullframe}
+slide mode as that saves resources needed for decoding video.
+
+The filter accepts the following options:
+
+@table @option
+@item sample_rate
+Specify sample rate of output audio, the sample rate of audio from which
+spectrum was generated may differ.
+
+@item channels
+Set number of channels represented in input video spectrums.
+
+@item scale
+Set scale which was used when generating magnitude input spectrum.
+Can be @code{lin} or @code{log}. Default is @code{log}.
+
+@item slide
+Set slide which was used when generating inputs spectrums.
+Can be @code{replace}, @code{scroll}, @code{fullframe} or @code{rscroll}.
+Default is @code{fullframe}.
+
+@item win_func
+Set window function used for resynthesis.
+
+@item overlap
+Set window overlap. In range @code{[0, 1]}. Default is @code{1},
+which means optimal overlap for selected window function will be picked.
+
+@item orientation
+Set orientation of input videos. Can be @code{vertical} or @code{horizontal}.
+Default is @code{vertical}.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+First create magnitude and phase videos from audio, assuming audio is stereo with 44100 sample rate,
+then resynthesize videos back to audio with spectrumsynth:
+@example
+ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=log:overlap=0.875:color=channel:slide=fullframe:data=magnitude -an -c:v rawvideo magnitude.nut
+ffmpeg -i input.flac -lavfi showspectrum=mode=separate:scale=lin:overlap=0.875:color=channel:slide=fullframe:data=phase -an -c:v rawvideo phase.nut
+ffmpeg -i magnitude.nut -i phase.nut -lavfi spectrumsynth=channels=2:sample_rate=44100:win_fun=hann:overlap=0.875:slide=fullframe output.flac
+@end example
+@end itemize
+
 @section split, asplit
 
 Split input into several identical outputs.