@anchor{afir}
@section afir
-Apply an arbitrary Frequency Impulse Response filter.
+Apply an arbitrary Finite Impulse Response filter.
This filter is designed for applying long FIR filters,
up to 60 seconds long.
room equalization, cross talk cancellation, wavefield synthesis,
auralization, ambiophonics, ambisonics and spatialization.
-This filter uses the second stream as FIR coefficients.
-If the second stream holds a single channel, it will be used
+This filter uses the streams higher than first one as FIR coefficients.
+If the non-first stream holds a single channel, it will be used
for all input channels in the first stream, otherwise
-the number of channels in the second stream must be same as
+the number of channels in the non-first stream must be same as
the number of channels in the first stream.
It accepts the following parameters:
@item minp
Set minimal partition size used for convolution. Default is @var{8192}.
-Allowed range is from @var{8} to @var{32768}.
+Allowed range is from @var{1} 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.
+
+@item nbirs
+Set number of input impulse responses streams which will be switchable at runtime.
+Allowed range is from @var{1} to @var{32}. Default is @var{1}.
+
+@item ir
+Set IR stream which will be used for convolution, starting from @var{0}, should always be
+lower than supplied value by @code{nbirs} option. Default is @var{0}.
+This option can be changed at runtime via @ref{commands}.
@end table
@subsection Examples
It accepts the following parameters:
@table @option
-@item sample_fmts
+@item sample_fmts, f
A '|'-separated list of requested sample formats.
-@item sample_rates
+@item sample_rates, r
A '|'-separated list of requested sample rates.
-@item channel_layouts
+@item channel_layouts, cl
A '|'-separated list of requested channel layouts.
See @ref{channel layout syntax,,the Channel Layout section in the ffmpeg-utils(1) manual,ffmpeg-utils}
Set additional parameter which controls sigmoid function.
@end table
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
@section asr
Automatic Speech Recognition
EBU R128 loudness normalization. Includes both dynamic and linear normalization modes.
Support for both single pass (livestreams, files) and double pass (files) modes.
-This algorithm can target IL, LRA, and maximum true peak. To accurately detect true peaks,
-the audio stream will be upsampled to 192 kHz unless the normalization mode is linear.
+This algorithm can target IL, LRA, and maximum true peak. In dynamic mode, to accurately
+detect true peaks, the audio stream will be upsampled to 192 kHz.
Use the @code{-ar} option or @code{aresample} filter to explicitly set an output sample rate.
The filter accepts the following options:
Range is -99.0 - +99.0. Default is +0.0.
@item linear
-Normalize linearly if possible.
-measured_I, measured_LRA, measured_TP, and measured_thresh must also
-to be specified in order to use this mode.
-Options are true or false. Default is true.
+Normalize by linearly scaling the source audio.
+@code{measured_I}, @code{measured_LRA}, @code{measured_TP},
+and @code{measured_thresh} must all be specified. Target LRA shouldn't
+be lower than source LRA and the change in integrated loudness shouldn't
+result in a true peak which exceeds the target TP. If any of these
+conditions aren't met, normalization mode will revert to @var{dynamic}.
+Options are @code{true} or @code{false}. Default is @code{true}.
@item dual_mono
Treat mono input files as "dual-mono". If a mono file is intended for playback
@end itemize
+@section afirsrc
+
+Generate a FIR coefficients using frequency sampling method.
+
+The resulting stream can be used with @ref{afir} filter for filtering the audio signal.
+
+The filter accepts the following options:
+
+@table @option
+@item taps, t
+Set number of filter coefficents in output audio stream.
+Default value is 1025.
+
+@item frequency, f
+Set frequency points from where magnitude and phase are set.
+This must be in non decreasing order, and first element must be 0, while last element
+must be 1. Elements are separated by white spaces.
+
+@item magnitude, m
+Set magnitude value for every frequency point set by @option{frequency}.
+Number of values must be same as number of frequency points.
+Values are separated by white spaces.
+
+@item phase, p
+Set phase value for every frequency point set by @option{frequency}.
+Number of values must be same as number of frequency points.
+Values are separated by white spaces.
+
+@item sample_rate, r
+Set sample rate, default is 44100.
+
+@item nb_samples, n
+Set number of samples per each frame. Default is 1024.
+
+@item win_func, w
+Set window function. Default is blackman.
+@end table
+
@section anullsrc
The null audio source, return unprocessed audio frames. It is mainly useful
@item color, colour, c
Specify the color of noise. Available noise colors are white, pink, brown,
-blue and violet. Default color is white.
+blue, violet and velvet. Default color is white.
@item seed, s
Specify a value used to seed the PRNG.
Detect video intervals that are (almost) completely black. Can be
useful to detect chapter transitions, commercials, or invalid
-recordings. Output lines contains the time for the start, end and
-duration of the detected black interval expressed in seconds.
+recordings.
-In order to display the output lines, you need to set the loglevel at
-least to the AV_LOG_INFO value.
+The filter outputs its detection analysis to both the log as well as
+frame metadata. If a black segment of at least the specified minimum
+duration is found, a line with the start and end timestamps as well
+as duration is printed to the log with level @code{info}. In addition,
+a log line with level @code{debug} is printed per frame showing the
+black amount detected for that frame.
+
+The filter also attaches metadata to the first frame of a black
+segment with key @code{lavfi.black_start} and to the first frame
+after the black segment ends with key @code{lavfi.black_end}. The
+value is the frame's timestamp. This metadata is added regardless
+of the minimum duration specified.
The filter accepts the following options:
@end table
-@section blend, tblend
+@anchor{blend}
+@section blend
Blend two video frames into each other.
The default value is @code{all}.
@end table
+@section cas
+
+Apply Contrast Adaptive Sharpen filter to video stream.
+
+The filter accepts the following options:
+
+@table @option
+@item strength
+Set the sharpening strength. Default value is 0.
+
+@item planes
+Set planes to filter. Default value is to filter all
+planes except alpha plane.
+@end table
+
@section chromahold
Remove all color information for all colors except for certain one.
@end example
@end itemize
+@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.
+
@section colorhold
Remove all color information for all RGB colors except for certain one.
Higher values result in more preserved color.
@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.
+
@section colorlevels
Adjust video input frames using levels.
@end example
@end itemize
+@subsection Commands
+
+This filter supports the all above options as @ref{commands}.
+
@section colormatrix
Convert color matrix.
@end itemize
+@anchor{derain}
@section derain
Remove the rain in the input image/video by applying the derain methods based on
backend can load files for only its format.
@end table
+It can also be finished with @ref{dnn_processing} filter.
+
@section deshake
Attempt to fix small changes in horizontal and/or vertical shift. This
@end example
@end itemize
+@anchor{dnn_processing}
@section dnn_processing
Do image processing with deep neural networks. It works together with another filter
@end table
+@subsection Examples
+
@itemize
@item
-Halve the red channle of the frame with format rgb24:
+Remove rain in rgb24 frame with can.pb (see @ref{derain} filter):
+@example
+./ffmpeg -i rain.jpg -vf format=rgb24,dnn_processing=dnn_backend=tensorflow:model=can.pb:input=x:output=y derain.jpg
+@end example
+
+@item
+Halve the pixel value of the frame with format gray32f:
+@example
+ffmpeg -i input.jpg -vf format=grayf32,dnn_processing=model=halve_gray_float.model:input=dnn_in:output=dnn_out:dnn_backend=native -y out.native.png
+@end example
+
+@item
+Handle the Y channel with srcnn.pb (see @ref{sr} filter) for frame with yuv420p (planar YUV formats supported):
+@example
+./ffmpeg -i 480p.jpg -vf format=yuv420p,scale=w=iw*2:h=ih*2,dnn_processing=dnn_backend=tensorflow:model=srcnn.pb:input=x:output=y -y srcnn.jpg
+@end example
+
+@item
+Handle the Y channel with espcn.pb (see @ref{sr} filter), which changes frame size, for format yuv420p (planar YUV formats supported):
@example
-ffmpeg -i input.jpg -vf format=rgb24,dnn_processing=model=halve_first_channel.model:input=dnn_in:output=dnn_out:dnn_backend=native out.native.png
+./ffmpeg -i 480p.jpg -vf format=yuv420p,dnn_processing=dnn_backend=tensorflow:model=espcn.pb:input=x:output=y -y tmp.espcn.jpg
@end example
@end itemize
@ref{video size syntax,,"Video size" section in the ffmpeg-utils manual,ffmpeg-utils}.
The default value is @code{900x256}.
+@item rate, r
+Set the output frame rate. Default value is @code{25}.
+
The foreground color expressions can use the following variables:
@table @option
@item MIN
drawtext=fontfile=FreeSans.ttf:text=cow:fontsize=24:x=80:y=20+24-max_glyph_a
@end example
+@item
+Plot special @var{lavf.image2dec.source_basename} metadata onto each frame if
+such metadata exists. Otherwise, plot the string "NA". Note that image2 demuxer
+must have option @option{-export_path_metadata 1} for the special metadata fields
+to be available for filters.
+@example
+drawtext="fontsize=20:fontcolor=white:fontfile=FreeSans.ttf:text='%@{metadata\:lavf.image2dec.source_basename\:NA@}':x=10:y=10"
+@end example
+
@end itemize
For more information about libfreetype, check:
Set freeze duration until notification (default is 2 seconds).
@end table
+@section freezeframes
+
+Freeze video frames.
+
+This filter freezes video frames using frame from 2nd input.
+
+The filter accepts the following options:
+
+@table @option
+@item first
+Set number of first frame from which to start freeze.
+
+@item last
+Set number of last frame from which to end freeze.
+
+@item replace
+Set number of frame from 2nd input which will be used instead of replaced frames.
+@end table
+
@anchor{frei0r}
@section frei0r
Return the value of the pixel at location (@var{x},@var{y}) of the alpha
plane. Return 0 if there is no such plane.
+@item psum(x,y), lumsum(x, y), cbsum(x,y), crsum(x,y), rsum(x,y), gsum(x,y), bsum(x,y), alphasum(x,y)
+Sum of sample values in the rectangle from (0,0) to (x,y), this allows obtaining
+sums of samples within a rectangle. See the functions without the sum postfix.
+
@item interpolation
Set one of interpolation methods:
@table @option
For functions, if @var{x} and @var{y} are outside the area, the value will be
automatically clipped to the closer edge.
+Please note that this filter can use multiple threads in which case each slice
+will have its own expression state. If you want to use only a single expression
+state because your expressions depend on previous state then you should limit
+the number of filter threads to 1.
+
@subsection Examples
@itemize
The device to upload to must be supplied when the filter is initialised. If
using ffmpeg, select the appropriate device with the @option{-filter_hw_device}
-option.
+option or with the @option{derive_device} option. The input and output devices
+must be of different types and compatible - the exact meaning of this is
+system-dependent, but typically it means that they must refer to the same
+underlying hardware context (for example, refer to the same graphics card).
+
+The following additional parameters are accepted:
+
+@table @option
+@item derive_device @var{type}
+Rather than using the device supplied at initialisation, instead derive a new
+device of type @var{type} from the device the input frames exist on.
+@end table
@anchor{hwupload_cuda}
@section hwupload_cuda
By default value is 0.
@end table
+The @code{hysteresis} filter also supports the @ref{framesync} options.
+
@section idet
Detect video interlacing type.
which means bit depth is automatically picked from first input format.
@end table
+The @code{lut2} filter also supports the @ref{framesync} options.
+
Each of them specifies the expression to use for computing the lookup table for
the corresponding pixel component values.
Set vertical radius size. Default value is @code{0}.
Allowed range is integer from 0 to 127.
If it is 0, value will be picked from horizontal @code{radius} option.
+
+@item percentile
+Set median percentile. Default value is @code{0.5}.
+Default value of @code{0.5} will pick always median values, while @code{0} will pick
+minimum values, and @code{1} maximum values.
@end table
@subsection Commands
@end itemize
+@anchor{overlay_cuda}
+@section overlay_cuda
+
+Overlay one video on top of another.
+
+This is the CUDA cariant of the @ref{overlay} filter.
+It only accepts CUDA frames. The underlying input pixel formats have to match.
+
+It takes two inputs and has one output. The first input is the "main"
+video on which the second input is overlaid.
+
+It accepts the following parameters:
+
+@table @option
+@item x
+@item y
+Set the x and y coordinates of the overlaid video on the main video.
+Default value is "0" for both expressions.
+
+@item eof_action
+See @ref{framesync}.
+
+@item shortest
+See @ref{framesync}.
+
+@item repeatlast
+See @ref{framesync}.
+
+@end table
+
+This filter also supports the @ref{framesync} options.
+
@section owdenoise
Apply Overcomplete Wavelet denoiser.
Set value which will be added to filtered result.
@end table
-@anchor{program_opencl}
-@section program_opencl
+@section pseudocolor
-Filter video using an OpenCL program.
+Alter frame colors in video with pseudocolors.
-@table @option
+This filter accepts the following options:
-@item source
-OpenCL program source file.
+@table @option
+@item c0
+set pixel first component expression
-@item kernel
-Kernel name in program.
+@item c1
+set pixel second component expression
-@item inputs
-Number of inputs to the filter. Defaults to 1.
+@item c2
+set pixel third component expression
-@item size, s
-Size of output frames. Defaults to the same as the first input.
+@item c3
+set pixel fourth component expression, corresponds to the alpha component
+@item i
+set component to use as base for altering colors
@end table
-The program source file must contain a kernel function with the given name,
-which will be run once for each plane of the output. Each run on a plane
-gets enqueued as a separate 2D global NDRange with one work-item for each
-pixel to be generated. The global ID offset for each work-item is therefore
-the coordinates of a pixel in the destination image.
+Each of them specifies the expression to use for computing the lookup table for
+the corresponding pixel component values.
-The kernel function needs to take the following arguments:
-@itemize
-@item
-Destination image, @var{__write_only image2d_t}.
+The expressions can contain the following constants and functions:
-This image will become the output; the kernel should write all of it.
-@item
-Frame index, @var{unsigned int}.
+@table @option
+@item w
+@item h
+The input width and height.
-This is a counter starting from zero and increasing by one for each frame.
-@item
-Source images, @var{__read_only image2d_t}.
+@item val
+The input value for the pixel component.
-These are the most recent images on each input. The kernel may read from
-them to generate the output, but they can't be written to.
-@end itemize
+@item ymin, umin, vmin, amin
+The minimum allowed component value.
-Example programs:
+@item ymax, umax, vmax, amax
+The maximum allowed component value.
+@end table
+
+All expressions default to "val".
+
+@subsection Examples
@itemize
@item
-Copy the input to the output (output must be the same size as the input).
-@verbatim
-__kernel void copy(__write_only image2d_t destination,
- unsigned int index,
- __read_only image2d_t source)
-{
- const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
+Change too high luma values to gradient:
+@example
+pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
+@end example
+@end itemize
- int2 location = (int2)(get_global_id(0), get_global_id(1));
+@section psnr
- float4 value = read_imagef(source, sampler, location);
+Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
+Ratio) between two input videos.
- write_imagef(destination, location, value);
-}
-@end verbatim
+This filter takes in input two input videos, the first input is
+considered the "main" source and is passed unchanged to the
+output. The second input is used as a "reference" video for computing
+the PSNR.
-@item
-Apply a simple transformation, rotating the input by an amount increasing
-with the index counter. Pixel values are linearly interpolated by the
-sampler, and the output need not have the same dimensions as the input.
-@verbatim
-__kernel void rotate_image(__write_only image2d_t dst,
- unsigned int index,
- __read_only image2d_t src)
-{
- const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
- CLK_FILTER_LINEAR);
+Both video inputs must have the same resolution and pixel format for
+this filter to work correctly. Also it assumes that both inputs
+have the same number of frames, which are compared one by one.
- float angle = (float)index / 100.0f;
+The obtained average PSNR is printed through the logging system.
- float2 dst_dim = convert_float2(get_image_dim(dst));
- float2 src_dim = convert_float2(get_image_dim(src));
+The filter stores the accumulated MSE (mean squared error) of each
+frame, and at the end of the processing it is averaged across all frames
+equally, and the following formula is applied to obtain the PSNR:
- float2 dst_cen = dst_dim / 2.0f;
- float2 src_cen = src_dim / 2.0f;
+@example
+PSNR = 10*log10(MAX^2/MSE)
+@end example
- int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
-
- float2 dst_pos = convert_float2(dst_loc) - dst_cen;
- float2 src_pos = {
- cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
- sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
- };
- src_pos = src_pos * src_dim / dst_dim;
-
- float2 src_loc = src_pos + src_cen;
-
- if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
- src_loc.x > src_dim.x || src_loc.y > src_dim.y)
- write_imagef(dst, dst_loc, 0.5f);
- else
- write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
-}
-@end verbatim
-
-@item
-Blend two inputs together, with the amount of each input used varying
-with the index counter.
-@verbatim
-__kernel void blend_images(__write_only image2d_t dst,
- unsigned int index,
- __read_only image2d_t src1,
- __read_only image2d_t src2)
-{
- const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
- CLK_FILTER_LINEAR);
-
- float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
-
- int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
- int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
- int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
-
- float4 val1 = read_imagef(src1, sampler, src1_loc);
- float4 val2 = read_imagef(src2, sampler, src2_loc);
-
- write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
-}
-@end verbatim
-
-@end itemize
-
-@section pseudocolor
-
-Alter frame colors in video with pseudocolors.
-
-This filter accepts the following options:
-
-@table @option
-@item c0
-set pixel first component expression
-
-@item c1
-set pixel second component expression
-
-@item c2
-set pixel third component expression
-
-@item c3
-set pixel fourth component expression, corresponds to the alpha component
-
-@item i
-set component to use as base for altering colors
-@end table
-
-Each of them specifies the expression to use for computing the lookup table for
-the corresponding pixel component values.
-
-The expressions can contain the following constants and functions:
-
-@table @option
-@item w
-@item h
-The input width and height.
-
-@item val
-The input value for the pixel component.
-
-@item ymin, umin, vmin, amin
-The minimum allowed component value.
-
-@item ymax, umax, vmax, amax
-The maximum allowed component value.
-@end table
-
-All expressions default to "val".
-
-@subsection Examples
-
-@itemize
-@item
-Change too high luma values to gradient:
-@example
-pseudocolor="'if(between(val,ymax,amax),lerp(ymin,ymax,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(umax,umin,(val-ymax)/(amax-ymax)),-1):if(between(val,ymax,amax),lerp(vmin,vmax,(val-ymax)/(amax-ymax)),-1):-1'"
-@end example
-@end itemize
-
-@section psnr
-
-Obtain the average, maximum and minimum PSNR (Peak Signal to Noise
-Ratio) between two input videos.
-
-This filter takes in input two input videos, the first input is
-considered the "main" source and is passed unchanged to the
-output. The second input is used as a "reference" video for computing
-the PSNR.
-
-Both video inputs must have the same resolution and pixel format for
-this filter to work correctly. Also it assumes that both inputs
-have the same number of frames, which are compared one by one.
-
-The obtained average PSNR is printed through the logging system.
-
-The filter stores the accumulated MSE (mean squared error) of each
-frame, and at the end of the processing it is averaged across all frames
-equally, and the following formula is applied to obtain the PSNR:
-
-@example
-PSNR = 10*log10(MAX^2/MSE)
-@end example
-
-Where MAX is the average of the maximum values of each component of the
-image.
+Where MAX is the average of the maximum values of each component of the
+image.
The description of the accepted parameters follows.
@item format
Specify pixel format of output from this filter. Can be @code{color} or @code{gray}.
Default is @code{color}.
+
+@item fill
+Specify the color of the unmapped pixels. For the syntax of this option,
+check the @ref{color syntax,,"Color" section in the ffmpeg-utils
+manual,ffmpeg-utils}. Default color is @code{black}.
@end table
@section removegrain
@item ovsub
horizontal and vertical output chroma subsample values. For example for the
pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
+
+@item n
+The (sequential) number of the input frame, starting from 0.
+Only available with @code{eval=frame}.
+
+@item t
+The presentation timestamp of the input frame, expressed as a number of
+seconds. Only available with @code{eval=frame}.
+
+@item pos
+The position (byte offset) of the frame in the input stream, or NaN if
+this information is unavailable and/or meaningless (for example in case of synthetic video).
+Only available with @code{eval=frame}.
@end table
@subsection Examples
The main input video's horizontal and vertical chroma subsample values.
For example for the pixel format "yuv422p" @var{hsub} is 2 and @var{vsub}
is 1.
+
+@item main_n
+The (sequential) number of the main input frame, starting from 0.
+Only available with @code{eval=frame}.
+
+@item main_t
+The presentation timestamp of the main input frame, expressed as a number of
+seconds. Only available with @code{eval=frame}.
+
+@item main_pos
+The position (byte offset) of the frame in the main input stream, or NaN if
+this information is unavailable and/or meaningless (for example in case of synthetic video).
+Only available with @code{eval=frame}.
@end table
@subsection Examples
@code{0} (not enabled).
@end table
+@subsection Commands
+
+This filter supports the following commands:
+@table @option
+@item quality, level
+Set quality level. The value @code{max} can be used to set the maximum level,
+currently @code{6}.
+@end table
+
+@anchor{sr}
@section sr
Scale the input by applying one of the super-resolution methods based on
input upscaled using bicubic upscaling with proper scale factor.
@end table
+This feature can also be finished with @ref{dnn_processing} filter.
+
@section ssim
Obtain the SSIM (Structural SImilarity Metric) between two input videos.
@section swapuv
Swap U & V plane.
+@section tblend
+Blend successive video frames.
+
+See @ref{blend}
+
@section telecine
Apply telecine process to the video.
@table @option
@item start
-Specify number of delay frames before input video stream.
+Specify number of delay frames before input video stream. Default is 0.
@item stop
Specify number of padding frames after input video stream.
-Set to -1 to pad indefinitely.
+Set to -1 to pad indefinitely. Default is 0.
@item start_mode
Set kind of frames added to beginning of stream.
Can be either @var{add} or @var{clone}.
With @var{add} frames of solid-color are added.
With @var{clone} frames are clones of first frame.
+Default is @var{add}.
@item stop_mode
Set kind of frames added to end of stream.
Can be either @var{add} or @var{clone}.
With @var{add} frames of solid-color are added.
With @var{clone} frames are clones of last frame.
+Default is @var{add}.
@item start_duration, stop_duration
Specify the duration of the start/stop delay. See
@ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}
for the accepted syntax.
-These options override @var{start} and @var{stop}.
+These options override @var{start} and @var{stop}. Default is 0.
@item color
Specify the color of the padded area. For the syntax of this option,
@item flat
@item gnomonic
@item rectilinear
-Regular video. @i{(output only)}
+Regular video.
Format specific options:
@table @option
@item h_fov
@item v_fov
@item d_fov
-Set horizontal/vertical/diagonal field of view. Values in degrees.
+Set output horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+
+@item ih_fov
+@item iv_fov
+@item id_fov
+Set input horizontal/vertical/diagonal field of view. Values in degrees.
If diagonal field of view is set it overrides horizontal and vertical field of view.
@end table
@item barrel
@item fb
-Facebook's 360 format.
+@item barrelsplit
+Facebook's 360 formats.
@item sg
Stereographic format.
@item h_fov
@item v_fov
@item d_fov
-Set horizontal/vertical/diagonal field of view. Values in degrees.
+Set output horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+
+@item ih_fov
+@item iv_fov
+@item id_fov
+Set input horizontal/vertical/diagonal field of view. Values in degrees.
If diagonal field of view is set it overrides horizontal and vertical field of view.
@end table
@item sinusoidal
Sinusoidal map projection format.
+@item fisheye
+Fisheye projection.
+
+Format specific options:
+@table @option
+@item h_fov
+@item v_fov
+@item d_fov
+Set output horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+
+@item ih_fov
+@item iv_fov
+@item id_fov
+Set input horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+@end table
+
+@item pannini
+Pannini projection.
+
+Format specific options:
+@table @option
+@item h_fov
+Set output pannini parameter.
+
+@item ih_fov
+Set input pannini parameter.
+@end table
+
+@item cylindrical
+Cylindrical projection.
+
+Format specific options:
+@table @option
+@item h_fov
+@item v_fov
+@item d_fov
+Set output horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+
+@item ih_fov
+@item iv_fov
+@item id_fov
+Set input horizontal/vertical/diagonal field of view. Values in degrees.
+
+If diagonal field of view is set it overrides horizontal and vertical field of view.
+@end table
+
+@item perspective
+Perspective projection. @i{(output only)}
+
+Format specific options:
+@table @option
+@item v_fov
+Set perspective parameter.
+@end table
+
+@item tetrahedron
+Tetrahedron projection.
+
+@item tsp
+Truncated square pyramid projection.
+
+@item he
+@item hequirect
+Half equirectangular projection.
@end table
@item interp
@item line
@item linear
Bilinear interpolation.
+@item lagrange9
+Lagrange9 interpolation.
@item cube
@item cubic
Bicubic interpolation.
@item lanc
@item lanczos
Lanczos interpolation.
+@item sp16
+@item spline16
+Spline16 interpolation.
+@item gauss
+@item gaussian
+Gaussian interpolation.
@end table
Default value is @b{@samp{line}}.
@item out_trans
Set if output video needs to be transposed. Boolean value, by default disabled.
+@item alpha_mask
+Build mask in alpha plane for all unmapped pixels by marking them fully transparent. Boolean value, by default disabled.
@end table
@subsection Examples
@end example
@end itemize
+@subsection Commands
+
+This filter supports subset of above options as @ref{commands}.
+
@section vaguedenoiser
Apply a wavelet based denoiser.
Default is @code{3}.
@end table
+@section xfade
+
+Apply cross fade from one input video stream to another input video stream.
+The cross fade is applied for specified duration.
+
+The filter accepts the following options:
+
+@table @option
+@item transition
+Set one of available transition effects:
+
+@table @samp
+@item custom
+@item fade
+@item wipeleft
+@item wiperight
+@item wipeup
+@item wipedown
+@item slideleft
+@item slideright
+@item slideup
+@item slidedown
+@item circlecrop
+@item rectcrop
+@item distance
+@item fadeblack
+@item fadewhite
+@item radial
+@item smoothleft
+@item smoothright
+@item smoothup
+@item smoothdown
+@item circleopen
+@item circleclose
+@item vertopen
+@item vertclose
+@item horzopen
+@item horzclose
+@item dissolve
+@item pixelize
+@item diagtl
+@item diagtr
+@item diagbl
+@item diagbr
+@item hlslice
+@item hrslice
+@item vuslice
+@item vdslice
+@end table
+Default transition effect is fade.
+
+@item duration
+Set cross fade duration in seconds.
+Default duration is 1 second.
+
+@item offset
+Set cross fade start relative to first input stream in seconds.
+Default offset is 0.
+
+@item expr
+Set expression for custom transition effect.
+
+The expressions can use the following variables and functions:
+
+@table @option
+@item X
+@item Y
+The coordinates of the current sample.
+
+@item W
+@item H
+The width and height of the image.
+
+@item P
+Progress of transition effect.
+
+@item PLANE
+Currently processed plane.
+
+@item A
+Return value of first input at current location and plane.
+
+@item B
+Return value of second input at current location and plane.
+
+@item a0(x, y)
+@item a1(x, y)
+@item a2(x, y)
+@item a3(x, y)
+Return the value of the pixel at location (@var{x},@var{y}) of the
+first/second/third/fourth component of first input.
+
+@item b0(x, y)
+@item b1(x, y)
+@item b2(x, y)
+@item b3(x, y)
+Return the value of the pixel at location (@var{x},@var{y}) of the
+first/second/third/fourth component of second input.
+@end table
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Cross fade from one input video to another input video, with fade transition and duration of transition
+of 2 seconds starting at offset of 5 seconds:
+@example
+ffmpeg -i first.mp4 -i second.mp4 -filter_complex xfade=transition=fade:duration=2:offset=5 output.mp4
+@end example
+@end itemize
+
@section xmedian
Pick median pixels from several input videos.
@item planes
Set which planes to filter. Default value is @code{15}, by which all planes are processed.
+
+@item percentile
+Set median percentile. Default value is @code{0.5}.
+Default value of @code{0.5} will pick always median values, while @code{0} will pick
+minimum values, and @code{1} maximum values.
@end table
@section xstack
@item shortest
If set to 1, force the output to terminate when the shortest input
terminates. Default value is 0.
+
+@item fill
+If set to valid color, all unused pixels will be filled with that color.
+By default fill is set to none, so it is disabled.
@end table
@subsection Examples
@end example
@end itemize
-@section convolution_opencl
-
-Apply convolution of 3x3, 5x5, 7x7 matrix.
+@section colorkey_opencl
+RGB colorspace color keying.
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, 25 or 49 signed numbers.
+@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.
+@end table
+
+@subsection Examples
+
+@itemize
+@item
+Make every semi-green pixel in the input transparent with some slight blending:
+@example
+-i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
+@end example
+@end itemize
+
+@section convolution_opencl
+
+Apply convolution of 3x3, 5x5, 7x7 matrix.
+
+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, 25 or 49 signed numbers.
Default value for each plane is @code{0 0 0 0 1 0 0 0 0}.
@item 0rdiv
@end example
@end itemize
-@section dilation_opencl
-
-Apply dilation effect to the video.
-
-This filter replaces the pixel by the local(3x3) maximum.
-
-It accepts the following options:
-
-@table @option
-@item threshold0
-@item threshold1
-@item threshold2
-@item threshold3
-Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
-If @code{0}, plane will remain unchanged.
-
-@item coordinates
-Flag which specifies the pixel to refer to.
-Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
-
-Flags to local 3x3 coordinates region centered on @code{x}:
-
- 1 2 3
-
- 4 x 5
-
- 6 7 8
-@end table
-
-@subsection Example
-
-@itemize
-@item
-Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane.
-@example
--i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
-@end example
-@end itemize
-
@section erosion_opencl
Apply erosion effect to the video.
@end example
@end itemize
-@section colorkey_opencl
-RGB colorspace color 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.
-@end table
-
-@subsection Examples
-
-@itemize
-@item
-Make every semi-green pixel in the input transparent with some slight blending:
-@example
--i INPUT -vf "hwupload, colorkey_opencl=green:0.3:0.1, hwdownload" OUTPUT
-@end example
-@end itemize
-
@section deshake_opencl
Feature-point based video stabilization filter.
@end example
@end itemize
+@section dilation_opencl
+
+Apply dilation effect to the video.
+
+This filter replaces the pixel by the local(3x3) maximum.
+
+It accepts the following options:
+
+@table @option
+@item threshold0
+@item threshold1
+@item threshold2
+@item threshold3
+Limit the maximum change for each plane. Range is @code{[0, 65535]} and default value is @code{65535}.
+If @code{0}, plane will remain unchanged.
+
+@item coordinates
+Flag which specifies the pixel to refer to.
+Range is @code{[0, 255]} and default value is @code{255}, i.e. all eight pixels are used.
+
+Flags to local 3x3 coordinates region centered on @code{x}:
+
+ 1 2 3
+
+ 4 x 5
+
+ 6 7 8
+@end table
+
+@subsection Example
+
+@itemize
+@item
+Apply dilation filter with threshold0 set to 30, threshold1 set 40, threshold2 set to 50 and coordinates set to 231, setting each pixel of the output to the local maximum between pixels: 1, 2, 3, 6, 7, 8 of the 3x3 region centered on it in the input. If the difference between input pixel and local maximum is more then threshold of the corresponding plane, output pixel will be set to input pixel + threshold of corresponding plane.
+@example
+-i INPUT -vf "hwupload, dilation_opencl=30:40:50:coordinates=231, hwdownload" OUTPUT
+@end example
+@end itemize
+
@section nlmeans_opencl
Non-local Means denoise filter through OpenCL, this filter accepts same options as @ref{nlmeans}.
@end itemize
+@section pad_opencl
+
+Add paddings to the input image, and place the original input at the
+provided @var{x}, @var{y} coordinates.
+
+It accepts the following options:
+
+@table @option
+@item width, w
+@item height, h
+Specify an expression for the size of the output image with the
+paddings added. If the value for @var{width} or @var{height} is 0, the
+corresponding input size is used for the output.
+
+The @var{width} expression can reference the value set by the
+@var{height} expression, and vice versa.
+
+The default value of @var{width} and @var{height} is 0.
+
+@item x
+@item y
+Specify the offsets to place the input image at within the padded area,
+with respect to the top/left border of the output image.
+
+The @var{x} expression can reference the value set by the @var{y}
+expression, and vice versa.
+
+The default value of @var{x} and @var{y} is 0.
+
+If @var{x} or @var{y} evaluate to a negative number, they'll be changed
+so the input image is centered on the padded area.
+
+@item color
+Specify the color of the padded area. For the syntax of this option,
+check the @ref{color syntax,,"Color" section in the ffmpeg-utils
+manual,ffmpeg-utils}.
+
+@item aspect
+Pad to an aspect instead to a resolution.
+@end table
+
+The value for the @var{width}, @var{height}, @var{x}, and @var{y}
+options are expressions containing the following constants:
+
+@table @option
+@item in_w
+@item in_h
+The input video width and height.
+
+@item iw
+@item ih
+These are the same as @var{in_w} and @var{in_h}.
+
+@item out_w
+@item out_h
+The output width and height (the size of the padded area), as
+specified by the @var{width} and @var{height} expressions.
+
+@item ow
+@item oh
+These are the same as @var{out_w} and @var{out_h}.
+
+@item x
+@item y
+The x and y offsets as specified by the @var{x} and @var{y}
+expressions, or NAN if not yet specified.
+
+@item a
+same as @var{iw} / @var{ih}
+
+@item sar
+input sample aspect ratio
+
+@item dar
+input display aspect ratio, it is the same as (@var{iw} / @var{ih}) * @var{sar}
+@end table
+
@section prewitt_opencl
Apply the Prewitt operator (@url{https://en.wikipedia.org/wiki/Prewitt_operator}) to input video stream.
@end example
@end itemize
+@anchor{program_opencl}
+@section program_opencl
+
+Filter video using an OpenCL program.
+
+@table @option
+
+@item source
+OpenCL program source file.
+
+@item kernel
+Kernel name in program.
+
+@item inputs
+Number of inputs to the filter. Defaults to 1.
+
+@item size, s
+Size of output frames. Defaults to the same as the first input.
+
+@end table
+
+The @code{program_opencl} filter also supports the @ref{framesync} options.
+
+The program source file must contain a kernel function with the given name,
+which will be run once for each plane of the output. Each run on a plane
+gets enqueued as a separate 2D global NDRange with one work-item for each
+pixel to be generated. The global ID offset for each work-item is therefore
+the coordinates of a pixel in the destination image.
+
+The kernel function needs to take the following arguments:
+@itemize
+@item
+Destination image, @var{__write_only image2d_t}.
+
+This image will become the output; the kernel should write all of it.
+@item
+Frame index, @var{unsigned int}.
+
+This is a counter starting from zero and increasing by one for each frame.
+@item
+Source images, @var{__read_only image2d_t}.
+
+These are the most recent images on each input. The kernel may read from
+them to generate the output, but they can't be written to.
+@end itemize
+
+Example programs:
+
+@itemize
+@item
+Copy the input to the output (output must be the same size as the input).
+@verbatim
+__kernel void copy(__write_only image2d_t destination,
+ unsigned int index,
+ __read_only image2d_t source)
+{
+ const sampler_t sampler = CLK_NORMALIZED_COORDS_FALSE;
+
+ int2 location = (int2)(get_global_id(0), get_global_id(1));
+
+ float4 value = read_imagef(source, sampler, location);
+
+ write_imagef(destination, location, value);
+}
+@end verbatim
+
+@item
+Apply a simple transformation, rotating the input by an amount increasing
+with the index counter. Pixel values are linearly interpolated by the
+sampler, and the output need not have the same dimensions as the input.
+@verbatim
+__kernel void rotate_image(__write_only image2d_t dst,
+ unsigned int index,
+ __read_only image2d_t src)
+{
+ const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
+ CLK_FILTER_LINEAR);
+
+ float angle = (float)index / 100.0f;
+
+ float2 dst_dim = convert_float2(get_image_dim(dst));
+ float2 src_dim = convert_float2(get_image_dim(src));
+
+ float2 dst_cen = dst_dim / 2.0f;
+ float2 src_cen = src_dim / 2.0f;
+
+ int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
+
+ float2 dst_pos = convert_float2(dst_loc) - dst_cen;
+ float2 src_pos = {
+ cos(angle) * dst_pos.x - sin(angle) * dst_pos.y,
+ sin(angle) * dst_pos.x + cos(angle) * dst_pos.y
+ };
+ src_pos = src_pos * src_dim / dst_dim;
+
+ float2 src_loc = src_pos + src_cen;
+
+ if (src_loc.x < 0.0f || src_loc.y < 0.0f ||
+ src_loc.x > src_dim.x || src_loc.y > src_dim.y)
+ write_imagef(dst, dst_loc, 0.5f);
+ else
+ write_imagef(dst, dst_loc, read_imagef(src, sampler, src_loc));
+}
+@end verbatim
+
+@item
+Blend two inputs together, with the amount of each input used varying
+with the index counter.
+@verbatim
+__kernel void blend_images(__write_only image2d_t dst,
+ unsigned int index,
+ __read_only image2d_t src1,
+ __read_only image2d_t src2)
+{
+ const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
+ CLK_FILTER_LINEAR);
+
+ float blend = (cos((float)index / 50.0f) + 1.0f) / 2.0f;
+
+ int2 dst_loc = (int2)(get_global_id(0), get_global_id(1));
+ int2 src1_loc = dst_loc * get_image_dim(src1) / get_image_dim(dst);
+ int2 src2_loc = dst_loc * get_image_dim(src2) / get_image_dim(dst);
+
+ float4 val1 = read_imagef(src1, sampler, src1_loc);
+ float4 val2 = read_imagef(src2, sampler, src2_loc);
+
+ write_imagef(dst, dst_loc, val1 * blend + val2 * (1.0f - blend));
+}
+@end verbatim
+
+@end itemize
+
@section roberts_opencl
Apply the Roberts cross operator (@url{https://en.wikipedia.org/wiki/Roberts_cross}) to input video stream.
@end example
@end itemize
+@section xfade_opencl
+
+Cross fade two videos with custom transition effect by using OpenCL.
+
+It accepts the following options:
+
+@table @option
+@item transition
+Set one of possible transition effects.
+
+@table @option
+@item custom
+Select custom transition effect, the actual transition description
+will be picked from source and kernel options.
+
+@item fade
+@item wipeleft
+@item wiperight
+@item wipeup
+@item wipedown
+@item slideleft
+@item slideright
+@item slideup
+@item slidedown
+
+Default transition is fade.
+@end table
+
+@item source
+OpenCL program source file for custom transition.
+
+@item kernel
+Set name of kernel to use for custom transition from program source file.
+
+@item duration
+Set duration of video transition.
+
+@item offset
+Set time of start of transition relative to first video.
+@end table
+
+The program source file must contain a kernel function with the given name,
+which will be run once for each plane of the output. Each run on a plane
+gets enqueued as a separate 2D global NDRange with one work-item for each
+pixel to be generated. The global ID offset for each work-item is therefore
+the coordinates of a pixel in the destination image.
+
+The kernel function needs to take the following arguments:
+@itemize
+@item
+Destination image, @var{__write_only image2d_t}.
+
+This image will become the output; the kernel should write all of it.
+
+@item
+First Source image, @var{__read_only image2d_t}.
+Second Source image, @var{__read_only image2d_t}.
+
+These are the most recent images on each input. The kernel may read from
+them to generate the output, but they can't be written to.
+
+@item
+Transition progress, @var{float}. This value is always between 0 and 1 inclusive.
+@end itemize
+
+Example programs:
+
+@itemize
+@item
+Apply dots curtain transition effect:
+@verbatim
+__kernel void blend_images(__write_only image2d_t dst,
+ __read_only image2d_t src1,
+ __read_only image2d_t src2,
+ float progress)
+{
+ const sampler_t sampler = (CLK_NORMALIZED_COORDS_FALSE |
+ CLK_FILTER_LINEAR);
+ int2 p = (int2)(get_global_id(0), get_global_id(1));
+ float2 rp = (float2)(get_global_id(0), get_global_id(1));
+ float2 dim = (float2)(get_image_dim(src1).x, get_image_dim(src1).y);
+ rp = rp / dim;
+
+ float2 dots = (float2)(20.0, 20.0);
+ float2 center = (float2)(0,0);
+ float2 unused;
+
+ float4 val1 = read_imagef(src1, sampler, p);
+ float4 val2 = read_imagef(src2, sampler, p);
+ bool next = distance(fract(rp * dots, &unused), (float2)(0.5, 0.5)) < (progress / distance(rp, center));
+
+ write_imagef(dst, p, next ? val1 : val2);
+}
+@end verbatim
+
+@end itemize
+
@c man end OPENCL VIDEO FILTERS
@chapter VAAPI Video Filters
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
+@section tonemap_vaapi
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.
for standard output. If @code{file} option is not set, output is written to the log
with AV_LOG_INFO loglevel.
+@item direct
+Reduces buffering in print mode when output is written to a URL set using @var{file}.
+
@end table
@subsection Examples
specified interval. In other words, the command is sent when the
previous frame timestamp was in the given interval, and the
current is not.
+
+@item expr
+The command @var{ARG} is interpreted as expression and result of
+expression is passed as @var{ARG}.
+
+The expression is evaluated through the eval API and can contain the following
+constants:
+
+@table @option
+@item POS
+Original position in the file of the frame, or undefined if undefined
+for the current frame.
+
+@item PTS
+The presentation timestamp in input.
+
+@item N
+The count of the input frame for video or audio, starting from 0.
+
+@item T
+The time in seconds of the current frame.
+
+@item TS
+The start time in seconds of the current command interval.
+
+@item TE
+The end time in seconds of the current command interval.
+
+@item TI
+The interpolated time of the current command interval, TI = (T - TS) / (TE - TS).
+@end table
+
@end table
If @var{FLAGS} is not specified, a default value of @code{[enter]} is
projects / ffmpeg / blobdiff