avfilter: add thistogram video filter
[ffmpeg.git] / doc / filters.texi
index 8fd85fd..619542e 100644 (file)
@@ -1547,6 +1547,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -2527,6 +2531,39 @@ ffmpeg -i INPUT -af atrim=end_sample=1000
 
 @end itemize
 
+@section axcorrelate
+Calculate normalized cross-correlation between two input audio streams.
+
+Resulted samples are always between -1 and 1 inclusive.
+If result is 1 it means two input samples are highly correlated in that selected segment.
+Result 0 means they are not correlated at all.
+If result is -1 it means two input samples are out of phase, which means they cancel each
+other.
+
+The filter accepts the following options:
+
+@table @option
+@item size
+Set size of segment over which cross-correlation is calculated.
+Default is 256. Allowed range is from 2 to 131072.
+
+@item algo
+Set algorithm for cross-correlation. Can be @code{slow} or @code{fast}.
+Default is @code{slow}. Fast algorithm assumes mean values over any given segment
+are always zero and thus need much less calculations to make.
+This is generally not true, but is valid for typical audio streams.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Calculate correlation between channels in stereo audio stream:
+@example
+ffmpeg -i stereo.wav -af channelsplit,axcorrelate=size=1024:algo=fast correlation.wav
+@end example
+@end itemize
+
 @section bandpass
 
 Apply a two-pole Butterworth band-pass filter with central
@@ -2568,6 +2605,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -2627,6 +2668,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -2693,6 +2738,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -2744,6 +2793,13 @@ Syntax for the command is : "@var{value}"
 @item mix, m
 How much to use filtered signal in output. Default is 1.
 Range is between 0 and 1.
+
+@item channels, c
+Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @section bs2b
@@ -3439,6 +3495,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Examples
@@ -3498,6 +3558,10 @@ Sets the difference coefficient (default: 2.5). 0.0 means mono sound
 Enable clipping. By default is enabled.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section firequalizer
 Apply FIR Equalization using arbitrary frequency response.
 
@@ -3908,6 +3972,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -4224,6 +4292,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Examples
@@ -5099,6 +5171,10 @@ channels. Default is 0.3.
 Set level of input signal of original channel. Default is 0.8.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options except @code{delay} as @ref{commands}.
+
 @section superequalizer
 Apply 18 band equalizer.
 
@@ -5332,6 +5408,10 @@ Range is between 0 and 1.
 
 @item channels, c
 Specify which channels to filter, by default all available are filtered.
+
+@item normalize, n
+Normalize biquad coefficients, by default is disabled.
+Enabling it will normalize magnitude response at DC to 0dB.
 @end table
 
 @subsection Commands
@@ -8282,6 +8362,9 @@ Draw rows and columns numbers on left and top of video.
 
 @item opacity
 Set background opacity.
+
+@item format
+Set display number format. Can be @code{hex}, or @code{dec}. Default is @code{hex}.
 @end table
 
 @section dctdnoiz
@@ -8557,6 +8640,10 @@ Limit the maximum change for each plane, default is 65535.
 If 0, plane will remain unchanged.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section deflicker
 
 Remove temporal frame luminance variations.
@@ -8898,6 +8985,10 @@ Flags to local 3x3 coordinates maps like this:
     6 7 8
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section displace
 
 Displace pixels as indicated by second and third input stream.
@@ -10046,6 +10137,10 @@ Flags to local 3x3 coordinates maps like this:
     6 7 8
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section extractplanes
 
 Extract color channel components from input video stream into
@@ -11599,6 +11694,7 @@ the histogram. Possible values are @code{none}, @code{weak} or
 @code{strong}. It defaults to @code{none}.
 @end table
 
+@anchor{histogram}
 @section histogram
 
 Compute and draw a color distribution histogram for the input video.
@@ -11693,6 +11789,13 @@ A floating point number which specifies chroma temporal strength. It defaults to
 @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}.
 @end table
 
+@subsection Commands
+This filter supports same @ref{commands} as options.
+The command accepts the same syntax of the corresponding option.
+
+If the specified expression is not valid, it is kept at its current
+value.
+
 @anchor{hwdownload}
 @section hwdownload
 
@@ -12086,6 +12189,10 @@ Default value is @code{none}.
 Swap luma/chroma/alpha fields. Exchange even & odd lines. Default value is @code{0}.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section inflate
 
 Apply inflate effect to the video.
@@ -12104,6 +12211,10 @@ Limit the maximum change for each plane, default is 65535.
 If 0, plane will remain unchanged.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @section interlace
 
 Simple interlacing filter from progressive contents. This interleaves upper (or
@@ -13597,6 +13708,13 @@ expensive no-op. Defaults to 1.0 (full strength).
 
 @end table
 
+@subsection Commands
+This filter supports same @ref{commands} as options, excluding @var{smoothing} option.
+The command accepts the same syntax of the corresponding option.
+
+If the specified expression is not valid, it is kept at its current
+value.
+
 @subsection Examples
 
 Stretch video contrast to use the full dynamic range, with no temporal
@@ -13810,6 +13928,13 @@ Draw some statistics. By default is enabled.
 Draw scope. By default is enabled.
 @end table
 
+@subsection Commands
+This filter supports same @ref{commands} as options.
+The command accepts the same syntax of the corresponding option.
+
+If the specified expression is not valid, it is kept at its current
+value.
+
 @subsection Examples
 
 @itemize
@@ -15252,42 +15377,16 @@ Set the line to start scanning for EIA-608 data. Default is @code{0}.
 @item scan_max
 Set the line to end scanning for EIA-608 data. Default is @code{29}.
 
-@item mac
-Set minimal acceptable amplitude change for sync codes detection.
-Default is @code{0.2}. Allowed range is @code{[0.001 - 1]}.
-
 @item spw
 Set the ratio of width reserved for sync code detection.
-Default is @code{0.27}. Allowed range is @code{[0.01 - 0.7]}.
-
-@item mhd
-Set the max peaks height difference for sync code detection.
-Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
-
-@item mpd
-Set max peaks period difference for sync code detection.
-Default is @code{0.1}. Allowed range is @code{[0.0 - 0.5]}.
-
-@item msd
-Set the first two max start code bits differences.
-Default is @code{0.02}. Allowed range is @code{[0.0 - 0.5]}.
-
-@item bhd
-Set the minimum ratio of bits height compared to 3rd start code bit.
-Default is @code{0.75}. Allowed range is @code{[0.01 - 1]}.
-
-@item th_w
-Set the white color threshold. Default is @code{0.35}. Allowed range is @code{[0.1 - 1]}.
-
-@item th_b
-Set the black color threshold. Default is @code{0.15}. Allowed range is @code{[0.0 - 0.5]}.
+Default is @code{0.27}. Allowed range is @code{[0.1 - 0.7]}.
 
 @item chp
 Enable checking the parity bit. In the event of a parity error, the filter will output
 @code{0x00} for that character. Default is false.
 
 @item lp
-Lowpass lines prior to further processing. Default is disabled.
+Lowpass lines prior to further processing. Default is enabled.
 @end table
 
 @subsection Examples
@@ -16117,6 +16216,46 @@ Supersampling
 @item lanczos
 @end table
 
+@item force_original_aspect_ratio
+Enable decreasing or increasing output video width or height if necessary to
+keep the original aspect ratio. Possible values:
+
+@table @samp
+@item disable
+Scale the video as specified and disable this feature.
+
+@item decrease
+The output video dimensions will automatically be decreased if needed.
+
+@item increase
+The output video dimensions will automatically be increased if needed.
+
+@end table
+
+One useful instance of this option is that when you know a specific device's
+maximum allowed resolution, you can use this to limit the output video to
+that, while retaining the aspect ratio. For example, device A allows
+1280x720 playback, and your video is 1920x800. Using this option (set it to
+decrease) and specifying 1280x720 to the command line makes the output
+1280x533.
+
+Please note that this is a different thing than specifying -1 for @option{w}
+or @option{h}, you still need to specify the output resolution for this option
+to work.
+
+@item force_divisible_by
+Ensures that both the output dimensions, width and height, are divisible by the
+given integer when used together with @option{force_original_aspect_ratio}. This
+works similar to using @code{-n} in the @option{w} and @option{h} options.
+
+This option respects the value set for @option{force_original_aspect_ratio},
+increasing or decreasing the resolution accordingly. The video's aspect ratio
+may be slightly modified.
+
+This option can be handy if you need to have a video fit within or exceed
+a defined resolution using @option{force_original_aspect_ratio} but also have
+encoder restrictions on width or height divisibility.
+
 @end table
 
 @section scale2ref
@@ -17607,6 +17746,55 @@ PAL output (25i):
 16p: 33333334
 @end example
 
+@section thistogram
+
+Compute and draw a color distribution histogram for the input video across time.
+
+Unlike @ref{histogram} video filter which only shows histogram of single input frame
+at certain time, this filter shows also past histograms of number of frames defined
+by @code{width} option.
+
+The computed histogram is a representation of the color component
+distribution in an image.
+
+The filter accepts the following options:
+
+@table @option
+@item width, w
+Set width of single color component output. Default value is @code{0}.
+Value of @code{0} means width will be picked from input video.
+This also set number of passed histograms to keep.
+Allowed range is [0, 8192].
+
+@item display_mode, d
+Set display mode.
+It accepts the following values:
+@table @samp
+@item stack
+Per color component graphs are placed below each other.
+
+@item parade
+Per color component graphs are placed side by side.
+
+@item overlay
+Presents information identical to that in the @code{parade}, except
+that the graphs representing color components are superimposed directly
+over one another.
+@end table
+Default is @code{stack}.
+
+@item levels_mode, m
+Set mode. Can be either @code{linear}, or @code{logarithmic}.
+Default is @code{linear}.
+
+@item components, c
+Set what color components to display.
+Default is @code{7}.
+
+@item bgopacity, b
+Set background opacity. Default is @code{0.5}.
+@end table
+
 @section threshold
 
 Apply threshold effect to video stream.
@@ -17986,10 +18174,12 @@ Enable complex vertical low-pass filtering.
 This will slightly less reduce interlace 'twitter' and Moire
 patterning but better retain detail and subjective sharpness impression.
 
+@item bypass_il
+Bypass already interlaced frames, only adjust the frame rate.
 @end table
 
-Vertical low-pass filtering can only be enabled for @option{mode}
-@var{interleave_top} and @var{interleave_bottom}.
+Vertical low-pass filtering and bypassing already interlaced frames can only be
+enabled for @option{mode} @var{interleave_top} and @var{interleave_bottom}.
 
 @end table
 
@@ -18805,6 +18995,7 @@ Set vectorscope mode.
 It accepts the following values:
 @table @samp
 @item gray
+@item tint
 Gray values are displayed on graph, higher brightness means more pixels have
 same component color value on location in graph. This is the default mode.
 
@@ -18863,6 +19054,7 @@ Set what kind of graticule to draw.
 @item none
 @item green
 @item color
+@item invert
 @end table
 
 @item opacity, o
@@ -18907,6 +19099,11 @@ Set what kind of colorspace to use when drawing graticule.
 @item 709
 @end table
 Default is auto.
+
+@item tint0, t0
+@item tint1, t1
+Set color tint for gray/tint vectorscope mode. By default both options are zero.
+This means no tint, and output will remain gray.
 @end table
 
 @anchor{vidstabdetect}
@@ -19195,6 +19392,10 @@ If @code{intensity} is negative and this is set to 1, colors will change,
 otherwise colors will be less saturated, more towards gray.
 @end table
 
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
 @anchor{vignette}
 @section vignette
 
@@ -19308,16 +19509,23 @@ vignette='PI/4+random(1)*PI/50':eval=frame
 
 @section vmafmotion
 
-Obtain the average vmaf motion score of a video.
-It is one of the component filters of VMAF.
+Obtain the average VMAF motion score of a video.
+It is one of the component metrics of VMAF.
 
 The obtained average motion score is printed through the logging system.
 
-In the below example the input file @file{ref.mpg} is being processed and score
-is computed.
+The filter accepts the following options:
 
+@table @option
+@item stats_file
+If specified, the filter will use the named file to save the motion score of
+each frame with respect to the previous frame.
+When filename equals "-" the data is sent to standard output.
+@end table
+
+Example:
 @example
-ffmpeg -i ref.mpg -lavfi vmafmotion -f null -
+ffmpeg -i ref.mpg -vf vmafmotion -f null -
 @end example
 
 @section vstack
@@ -19531,6 +19739,12 @@ Default is digital.
 
 @item bgopacity, b
 Set background opacity.
+
+@item tint0, t0
+@item tint1, t1
+Set tint for output.
+Only used with lowpass filter and when display is not overlay and input
+pixel formats are not RGB.
 @end table
 
 @section weave, doubleweave
@@ -19818,6 +20032,28 @@ Only deinterlace frames marked as interlaced.
 The default value is @code{all}.
 @end table
 
+@section yaepblur
+
+Apply blur filter while preserving edges ("yaepblur" means "yet another edge preserving blur filter").
+The algorithm is described in
+"J. S. Lee, Digital image enhancement and noise filtering by use of local statistics, IEEE Trans. Pattern Anal. Mach. Intell. PAMI-2, 1980."
+
+It accepts the following parameters:
+
+@table @option
+@item radius, r
+Set the window radius. Default value is 3.
+
+@item planes, p
+Set which planes to filter. Default is only the first plane.
+
+@item sigma, s
+Set blur strength. Default value is 128.
+@end table
+
+@subsection Commands
+This filter supports same @ref{commands} as options.
+
 @section zoompan
 
 Apply Zoom & Pan effect.
@@ -20872,6 +21108,65 @@ Apply a strong blur of both luma and chroma parameters:
 
 @c man end OPENCL VIDEO FILTERS
 
+@chapter VAAPI Video Filters
+@c man begin VAAPI VIDEO FILTERS
+
+VAAPI Video filters are usually used with VAAPI decoder and VAAPI encoder. Below is a description of VAAPI video filters.
+
+To enable compilation of these filters you need to configure FFmpeg with
+@code{--enable-vaapi}.
+
+To use vaapi filters, you need to setup the vaapi device correctly. For more information, please read @url{https://trac.ffmpeg.org/wiki/Hardware/VAAPI}
+
+@section tonemap_vappi
+
+Perform HDR(High Dynamic Range) to SDR(Standard Dynamic Range) conversion with tone-mapping.
+It maps the dynamic range of HDR10 content to the SDR content.
+It currently only accepts HDR10 as input.
+
+It accepts the following parameters:
+
+@table @option
+@item format
+Specify the output pixel format.
+
+Currently supported formats are:
+@table @var
+@item p010
+@item nv12
+@end table
+
+Default is nv12.
+
+@item primaries, p
+Set the output color primaries.
+
+Default is same as input.
+
+@item transfer, t
+Set the output transfer characteristics.
+
+Default is bt709.
+
+@item matrix, m
+Set the output colorspace matrix.
+
+Default is same as input.
+
+@end table
+
+@subsection Example
+
+@itemize
+@item
+Convert HDR(HDR10) video to bt2020-transfer-characteristic p010 format
+@example
+tonemap_vaapi=format=p010:t=bt2020-10
+@end example
+@end itemize
+
+@c man end VAAPI VIDEO FILTERS
+
 @chapter Video Sources
 @c man begin VIDEO SOURCES