@section Notes on filtergraph escaping
-Some filter arguments require the use of special characters, typically
-@code{:} to separate key=value pairs in a named options list. In this
-case the user should perform a first level escaping when specifying
-the filter arguments. For example, consider the following literal
-string to be embedded in the @ref{drawtext} filter arguments:
+Filtergraph description composition entails several levels of
+escaping. See @ref{quoting_and_escaping,,the "Quoting and escaping"
+section in the ffmpeg-utils(1) manual,ffmpeg-utils} for more
+information about the employed escaping procedure.
+
+A first level escaping affects the content of each filter option
+value, which may contain the special character @code{:} used to
+separate values, or one of the escaping characters @code{\'}.
+
+A second level escaping affects the whole filter description, which
+may contain the escaping characters @code{\'} or the special
+characters @code{[],;} used by the filtergraph description.
+
+Finally, when you specify a filtergraph on a shell commandline, you
+need to perform a third level escaping for the shell special
+characters contained within it.
+
+For example, consider the following string to be embedded in
+the @ref{drawtext} filter description @option{text} value:
@example
this is a 'string': may contain one, or more, special characters
@end example
-Since @code{:} is special for the filter arguments syntax, it needs to
-be escaped, so you get:
+This string contains the @code{'} special escaping character, and the
+@code{:} special character, so it needs to be escaped in this way:
@example
text=this is a \'string\'\: may contain one, or more, special characters
@end example
A second level of escaping is required when embedding the filter
-arguments in a filtergraph description, in order to escape all the
+description in a filtergraph description, in order to escape all the
filtergraph special characters. Thus the example above becomes:
@example
drawtext=text=this is a \\\'string\\\'\\: may contain one\, or more\, special characters
@end example
+(note that in addition to the @code{\'} escaping special characters,
+also @code{,} needs to be escaped).
-Finally an additional level of escaping may be needed when writing the
+Finally an additional level of escaping is needed when writing the
filtergraph description in a shell command, which depends on the
escaping rules of the adopted shell. For example, assuming that
@code{\} is special and needs to be escaped with another @code{\}, the
-vf "drawtext=text=this is a \\\\\\'string\\\\\\'\\\\: may contain one\\, or more\\, special characters"
@end example
-Sometimes, it might be more convenient to employ quoting in place of
-escaping. For example the string:
-@example
-Caesar: tu quoque, Brute, fili mi
-@end example
-
-Can be quoted in the filter arguments as:
-@example
-text='Caesar: tu quoque, Brute, fili mi'
-@end example
-
-And finally inserted in a filtergraph like:
-@example
-drawtext=text=\'Caesar: tu quoque\, Brute\, fili mi\'
-@end example
-
-See the ``Quoting and escaping'' section in the ffmpeg-utils manual
-for more information about the escaping and quoting rules adopted by
-FFmpeg.
-
@chapter Timeline editing
Some filters support a generic @option{enable} option. For the filters
The default value of @var{boxcolor} is "white".
+@item borderw
+Set the width of the border to be drawn around the text using @var{bordercolor}.
+The default value of @var{borderw} is 0.
+
+@item bordercolor
+Set the color to be used for drawing border around text. For the syntax of this
+option, check the "Color" section in the ffmpeg-utils manual.
+
+The default value of @var{bordercolor} is "black".
+
@item expansion
Select how the @var{text} is expanded. Can be either @code{none},
@code{strftime} (deprecated) or
@item no_autohint
@end table
-Default value is "render".
+Default value is "default".
For more information consult the documentation for the FT_LOAD_*
libfreetype flags.
other specified dimension. If both of them are -1, the input size is
used
+If one of the values is -n with n > 1, the scale filter will also use a value
+that maintains the aspect ratio of the input image, calculated from the other
+specified dimension. After that it will, however, make sure that the calculated
+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.
To enable compilation of this filter you need to configure FFmpeg with
@code{--enable-libvidstab}.
-This filter accepts the following options:
+@subsection Options
@table @option
-
@item input
-path to the file used to read the transforms (default: @file{transforms.trf})
+Set path to the file used to read the transforms. Default value is
+@file{transforms.trf}).
@item smoothing
-Set the number of frames (value*2 + 1) used for lowpass filtering the camera movements
-(default: 10). For example a number of 10 means that 21 frames are used
-(10 in the past and 10 in the future) to smoothen the motion in the
-video. A larger values leads to a smoother video, but limits the
-acceleration of the camera (pan/tilt movements).
-0 is a special case where a static camera is simulated.
+Set the number of frames (value*2 + 1) used for lowpass filtering the
+camera movements. Default value is 10.
+
+For example a number of 10 means that 21 frames are used (10 in the
+past and 10 in the future) to smoothen the motion in the video. A
+larger values leads to a smoother video, but limits the acceleration
+of the camera (pan/tilt movements). 0 is a special case where a
+static camera is simulated.
@item optalgo
-Set the camera path optimization algorithm:
+Set the camera path optimization algorithm.
+
+Accepted values are:
@table @samp
@item gauss
gaussian kernel low-pass filter on camera motion (default)
@end table
@item maxshift
-maximal number of pixels to translate frames (default: -1 no limit)
+Set maximal number of pixels to translate frames. Default value is -1,
+meaning no limit.
@item maxangle
-maximal angle in radians (degree*PI/180) to rotate frames (default: -1
-no limit)
+Set maximal angle in radians (degree*PI/180) to rotate frames. Default
+value is -1, meaning no limit.
@item crop
-How to deal with borders that may be visible due to movement
-compensation. Available values are:
+Specify how to deal with borders that may be visible due to movement
+compensation.
+Available values are:
@table @samp
@item keep
keep image information from previous frame (default)
@end table
@item invert
-@table @samp
-@item 0
-keep transforms normal (default)
-@item 1
-invert transforms
-@end table
+Invert transforms if set to 1. Default value is 0.
@item relative
-consider transforms as
-@table @samp
-@item 0
-absolute
-@item 1
-relative to previous frame (default)
-@end table
+Consider transforms as relative to previsou frame if set to 1,
+absolute if set to 0. Default value is 0.
@item zoom
-Set percentage to zoom (default: 0)
-@table @samp
-@item >0
-zoom in
-@item <0
-zoom out
-@end table
+Set percentage to zoom. A positive value will result in a zoom-in
+effect, a negative value in a zoom-out effect. Default value is 0 (no
+zoom).
@item optzoom
-Set optimal zooming to avoid borders
+Set optimal zooming to avoid borders.
+
+Accepted values are:
@table @samp
@item 0
disabled
@item 1
-optimal static zoom value is determined (only very strong movements will lead to visible borders) (default)
+optimal static zoom value is determined (only very strong movements
+will lead to visible borders) (default)
@item 2
-optimal adaptive zoom value is determined (no borders will be visible), see @option{zoomspeed}
+optimal adaptive zoom value is determined (no borders will be
+visible), see @option{zoomspeed}
@end table
-Note that the value given at zoom is added to the one calculated
-here.
+
+Note that the value given at zoom is added to the one calculated here.
@item zoomspeed
-Set percent to zoom maximally each frame (for @option{optzoom=2}). Range is from 0 to 5, default value is 0.2
+Set percent to zoom maximally each frame (enabled when
+@option{optzoom} is set to 2). Range is from 0 to 5, default value is
+0.25.
@item interpol
-type of interpolation
+Specify type of interpolation.
Available values are:
@table @samp
@end table
@item tripod
-virtual tripod mode means that the video is stabilized such that the
-camera stays stationary. Use also @code{tripod} option of
-@ref{vidstabdetect}.
-@table @samp
-@item 0
-off (default)
-@item 1
-virtual tripod mode: equivalent to @code{relative=0:smoothing=0}
-@end table
+Enable virtual tripod mode if set to 1, which is equivalent to
+@code{relative=0:smoothing=0}. Default value is 0.
-@item debug
-Increase log verbosity of set to 1. Also the detected global motions are written to the temporary file @file{global_motions.trf}.
-@table @samp
-@item 0
-disabled (default)
-@item 1
-enabled
-@end table
+Use also @code{tripod} option of @ref{vidstabdetect}.
+@item debug
+Increase log verbosity if set to 1. Also the detected global motions
+are written to the temporary file @file{global_motions.trf}. Default
+value is 0.
@end table
@subsection Examples
@itemize
@item
-typical call with default default values:
- (note the unsharp filter which is always recommended)
+Use @command{ffmpeg} for a typical stabilization with default values:
@example
ffmpeg -i inp.mpeg -vf vidstabtransform,unsharp=5:5:0.8:3:3:0.4 inp_stabilized.mpeg
@end example
+Note the use of the unsharp filter which is always recommended.
+
@item
-zoom in a bit more and load transform data from a given file
+Zoom in a bit more and load transform data from a given file:
@example
vidstabtransform=zoom=5:input="mytransforms.trf"
@end example
@item
-smoothen the video even more
+Smoothen the video even more:
@example
vidstabtransform=smoothing=30
@end example
-
@end itemize
@section vflip