[FFmpeg-devel] [PATCH] doc/filters: sort audio filters by name

Stefano Sabatini stefasab at gmail.com
Fri May 10 13:27:50 CEST 2013


---
 doc/filters.texi | 1130 +++++++++++++++++++++++++++---------------------------
 1 file changed, 568 insertions(+), 562 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index c979123..73bb72b 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -347,158 +347,133 @@ aconvert=u8:auto
 @end example
 @end itemize
 
- at section allpass
-
-Apply a two-pole all-pass filter with central frequency (in Hz)
- at var{frequency}, and filter-width @var{width}.
-An all-pass filter changes the audio's frequency to phase relationship
-without changing its frequency to amplitude relationship.
+ at section afade
 
-The filter accepts the following options:
+Apply fade-in/out effect to input audio.
 
- at table @option
- at item frequency, f
-Set frequency in Hz.
+A description of the accepted parameters follows.
 
- at item width_type
-Set method to specify band-width of filter.
 @table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
- at end table
-
- at item width, w
-Specify the band-width of a filter in width_type units.
- at end table
+ at item type, t
+Specify the effect type, can be either @code{in} for fade-in, or
+ at code{out} for a fade-out effect. Default is @code{in}.
 
- at section highpass
+ at item start_sample, ss
+Specify the number of the start sample for starting to apply the fade
+effect. Default is 0.
 
-Apply a high-pass filter with 3dB point frequency.
-The filter can be either single-pole, or double-pole (the default).
-The filter roll off at 6dB per pole per octave (20dB per pole per decade).
+ at item nb_samples, ns
+Specify the number of samples for which the fade effect has to last. At
+the end of the fade-in effect the output audio will have the same
+volume as the input audio, at the end of the fade-out transition
+the output audio will be silence. Default is 44100.
 
-The filter accepts the following options:
+ at item start_time, st
+Specify time for starting to apply the fade effect. Default is 0.
+The accepted syntax is:
+ at example
+[-]HH[:MM[:SS[.m...]]]
+[-]S+[.m...]
+ at end example
+See also the function @code{av_parse_time()}.
+If set this option is used instead of @var{start_sample} one.
 
- at table @option
- at item frequency, f
-Set frequency in Hz. Default is 3000.
+ at item duration, d
+Specify the duration for which the fade effect has to last. Default is 0.
+The accepted syntax is:
+ at example
+[-]HH[:MM[:SS[.m...]]]
+[-]S+[.m...]
+ at end example
+See also the function @code{av_parse_time()}.
+At the end of the fade-in effect the output audio will have the same
+volume as the input audio, at the end of the fade-out transition
+the output audio will be silence.
+If set this option is used instead of @var{nb_samples} one.
 
- at item poles, p
-Set number of poles. Default is 2.
+ at item curve
+Set curve for fade transition.
 
- at item width_type
-Set method to specify band-width of filter.
+It accepts the following values:
 @table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
+ at item tri
+select triangular, linear slope (default)
+ at item qsin
+select quarter of sine wave
+ at item hsin
+select half of sine wave
+ at item esin
+select exponential sine wave
+ at item log
+select logarithmic
+ at item par
+select inverted parabola
+ at item qua
+select quadratic
+ at item cub
+select cubic
+ at item squ
+select square root
+ at item cbr
+select cubic root
 @end table
-
- at item width, w
-Specify the band-width of a filter in width_type units.
-Applies only to double-pole filter.
-The default is 0.707q and gives a Butterworth response.
 @end table
 
- at section lowpass
+ at subsection Examples
 
-Apply a low-pass filter with 3dB point frequency.
-The filter can be either single-pole or double-pole (the default).
-The filter roll off at 6dB per pole per octave (20dB per pole per decade).
+ at itemize
+ at item
+Fade in first 15 seconds of audio:
+ at example
+afade=t=in:ss=0:d=15
+ at end example
 
-The filter accepts the following options:
+ at item
+Fade out last 25 seconds of a 900 seconds audio:
+ at example
+afade=t=out:st=875:d=25
+ at end example
+ at end itemize
 
- at table @option
- at item frequency, f
-Set frequency in Hz. Default is 500.
+ at anchor{aformat}
+ at section aformat
 
- at item poles, p
-Set number of poles. Default is 2.
+Set output format constraints for the input audio. The framework will
+negotiate the most appropriate format to minimize conversions.
 
- at item width_type
-Set method to specify band-width of filter.
+The filter accepts the following named parameters:
 @table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
- at end table
-
- at item width, w
-Specify the band-width of a filter in width_type units.
-Applies only to double-pole filter.
-The default is 0.707q and gives a Butterworth response.
- at end table
-
- at section bass
-
-Boost or cut the bass (lower) frequencies of the audio using a two-pole
-shelving filter with a response similar to that of a standard
-hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
 
-The filter accepts the following options:
+ at item sample_fmts
+A '|'-separated list of requested sample formats.
 
- at table @option
- at item gain, g
-Give the gain at 0 Hz. Its useful range is about -20
-(for a large cut) to +20 (for a large boost).
-Beware of clipping when using a positive gain.
+ at item sample_rates
+A '|'-separated list of requested sample rates.
 
- at item frequency, f
-Set the filter's central frequency and so can be used
-to extend or reduce the frequency range to be boosted or cut.
-The default value is @code{100} Hz.
+ at item channel_layouts
+A '|'-separated list of requested channel layouts.
 
- at item width_type
-Set method to specify band-width of filter.
- at table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
 @end table
 
- at item width, w
-Determine how steep is the filter's shelf transition.
- at end table
+If a parameter is omitted, all values are allowed.
 
- at section treble
+For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
+ at example
+aformat=sample_fmts=u8|s16:channel_layouts=stereo
+ at end example
 
-Boost or cut treble (upper) frequencies of the audio using a two-pole
-shelving filter with a response similar to that of a standard
-hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
+ at section allpass
+
+Apply a two-pole all-pass filter with central frequency (in Hz)
+ at var{frequency}, and filter-width @var{width}.
+An all-pass filter changes the audio's frequency to phase relationship
+without changing its frequency to amplitude relationship.
 
 The filter accepts the following options:
 
 @table @option
- at item gain, g
-Give the gain at whichever is the lower of ~22 kHz and the
-Nyquist frequency. Its useful range is about -20 (for a large cut)
-to +20 (for a large boost). Beware of clipping when using a positive gain.
-
 @item frequency, f
-Set the filter's central frequency and so can be used
-to extend or reduce the frequency range to be boosted or cut.
-The default value is @code{3000} Hz.
+Set frequency in Hz.
 
 @item width_type
 Set method to specify band-width of filter.
@@ -514,255 +489,34 @@ slope
 @end table
 
 @item width, w
-Determine how steep is the filter's shelf transition.
+Specify the band-width of a filter in width_type units.
 @end table
 
- at section bandpass
+ at section amerge
 
-Apply a two-pole Butterworth band-pass filter with central
-frequency @var{frequency}, and (3dB-point) band-width width.
-The @var{csg} option selects a constant skirt gain (peak gain = Q)
-instead of the default: constant 0dB peak gain.
-The filter roll off at 6dB per octave (20dB per decade).
+Merge two or more audio streams into a single multi-channel stream.
 
 The filter accepts the following options:
 
 @table @option
- at item frequency, f
-Set the filter's central frequency. Default is @code{3000}.
 
- at item csg
-Constant skirt gain if set to 1. Defaults to 0.
+ at item inputs
+Set the number of inputs. Default is 2.
 
- at item width_type
-Set method to specify band-width of filter.
- at table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
 @end table
 
- at item width, w
-Specify the band-width of a filter in width_type units.
- at end table
+If the channel layouts of the inputs are disjoint, and therefore compatible,
+the channel layout of the output will be set accordingly and the channels
+will be reordered as necessary. If the channel layouts of the inputs are not
+disjoint, the output will have all the channels of the first input then all
+the channels of the second input, in that order, and the channel layout of
+the output will be the default value corresponding to the total number of
+channels.
 
- at section bandreject
-
-Apply a two-pole Butterworth band-reject filter with central
-frequency @var{frequency}, and (3dB-point) band-width @var{width}.
-The filter roll off at 6dB per octave (20dB per decade).
-
-The filter accepts the following options:
-
- at table @option
- at item frequency, f
-Set the filter's central frequency. Default is @code{3000}.
-
- at item width_type
-Set method to specify band-width of filter.
- at table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
- at end table
-
- at item width, w
-Specify the band-width of a filter in width_type units.
- at end table
-
- at section biquad
-
-Apply a biquad IIR filter with the given coefficients.
-Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
-are the numerator and denominator coefficients respectively.
-
- at section equalizer
-
-Apply a two-pole peaking equalisation (EQ) filter. With this
-filter, the signal-level at and around a selected frequency can
-be increased or decreased, whilst (unlike bandpass and bandreject
-filters) that at all other frequencies is unchanged.
-
-In order to produce complex equalisation curves, this filter can
-be given several times, each with a different central frequency.
-
-The filter accepts the following options:
-
- at table @option
- at item frequency, f
-Set the filter's central frequency in Hz.
-
- at item width_type
-Set method to specify band-width of filter.
- at table @option
- at item h
-Hz
- at item q
-Q-Factor
- at item o
-octave
- at item s
-slope
- at end table
-
- at item width, w
-Specify the band-width of a filter in width_type units.
-
- at item gain, g
-Set the required gain or attenuation in dB.
-Beware of clipping when using a positive gain.
- at end table
-
- at section afade
-
-Apply fade-in/out effect to input audio.
-
-A description of the accepted parameters follows.
-
- at table @option
- at item type, t
-Specify the effect type, can be either @code{in} for fade-in, or
- at code{out} for a fade-out effect. Default is @code{in}.
-
- at item start_sample, ss
-Specify the number of the start sample for starting to apply the fade
-effect. Default is 0.
-
- at item nb_samples, ns
-Specify the number of samples for which the fade effect has to last. At
-the end of the fade-in effect the output audio will have the same
-volume as the input audio, at the end of the fade-out transition
-the output audio will be silence. Default is 44100.
-
- at item start_time, st
-Specify time for starting to apply the fade effect. Default is 0.
-The accepted syntax is:
- at example
-[-]HH[:MM[:SS[.m...]]]
-[-]S+[.m...]
- at end example
-See also the function @code{av_parse_time()}.
-If set this option is used instead of @var{start_sample} one.
-
- at item duration, d
-Specify the duration for which the fade effect has to last. Default is 0.
-The accepted syntax is:
- at example
-[-]HH[:MM[:SS[.m...]]]
-[-]S+[.m...]
- at end example
-See also the function @code{av_parse_time()}.
-At the end of the fade-in effect the output audio will have the same
-volume as the input audio, at the end of the fade-out transition
-the output audio will be silence.
-If set this option is used instead of @var{nb_samples} one.
-
- at item curve
-Set curve for fade transition.
-
-It accepts the following values:
- at table @option
- at item tri
-select triangular, linear slope (default)
- at item qsin
-select quarter of sine wave
- at item hsin
-select half of sine wave
- at item esin
-select exponential sine wave
- at item log
-select logarithmic
- at item par
-select inverted parabola
- at item qua
-select quadratic
- at item cub
-select cubic
- at item squ
-select square root
- at item cbr
-select cubic root
- at end table
- at end table
-
- at subsection Examples
-
- at itemize
- at item
-Fade in first 15 seconds of audio:
- at example
-afade=t=in:ss=0:d=15
- at end example
-
- at item
-Fade out last 25 seconds of a 900 seconds audio:
- at example
-afade=t=out:st=875:d=25
- at end example
- at end itemize
-
- at anchor{aformat}
- at section aformat
-
-Set output format constraints for the input audio. The framework will
-negotiate the most appropriate format to minimize conversions.
-
-The filter accepts the following named parameters:
- at table @option
-
- at item sample_fmts
-A '|'-separated list of requested sample formats.
-
- at item sample_rates
-A '|'-separated list of requested sample rates.
-
- at item channel_layouts
-A '|'-separated list of requested channel layouts.
-
- at end table
-
-If a parameter is omitted, all values are allowed.
-
-For example to force the output to either unsigned 8-bit or signed 16-bit stereo:
- at example
-aformat=sample_fmts=u8|s16:channel_layouts=stereo
- at end example
-
- at section amerge
-
-Merge two or more audio streams into a single multi-channel stream.
-
-The filter accepts the following options:
-
- at table @option
-
- at item inputs
-Set the number of inputs. Default is 2.
-
- at end table
-
-If the channel layouts of the inputs are disjoint, and therefore compatible,
-the channel layout of the output will be set accordingly and the channels
-will be reordered as necessary. If the channel layouts of the inputs are not
-disjoint, the output will have all the channels of the first input then all
-the channels of the second input, in that order, and the channel layout of
-the output will be the default value corresponding to the total number of
-channels.
-
-For example, if the first input is in 2.1 (FL+FR+LF) and the second input
-is FC+BL+BR, then the output will be in 5.1, with the channels in the
-following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
-first input, b1 is the first channel of the second input).
+For example, if the first input is in 2.1 (FL+FR+LF) and the second input
+is FC+BL+BR, then the output will be in 5.1, with the channels in the
+following order: a1, a2, b1, a3, b2, b3 (a1 is the first channel of the
+first input, b1 is the first channel of the second input).
 
 On the other hand, if both input are in stereo, the output channels will be
 in the default order: a1, a2, b1, b2, and the channel layout will be
@@ -1071,6 +825,39 @@ amovie=file.ogg [a] ; amovie=file.mp3 [b] ;
 [a2] [b2] amerge
 @end example
 
+ at section asyncts
+
+Synchronize audio data with timestamps by squeezing/stretching it and/or
+dropping samples/adding silence when needed.
+
+This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
+
+The filter accepts the following named parameters:
+ at table @option
+
+ at item compensate
+Enable stretching/squeezing the data to make it match the timestamps. Disabled
+by default. When disabled, time gaps are covered with silence.
+
+ at item min_delta
+Minimum difference between timestamps and audio data (in seconds) to trigger
+adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
+this filter, try setting this parameter to 0.
+
+ at item max_comp
+Maximum compensation in samples per second. Relevant only with compensate=1.
+Default value 500.
+
+ at item first_pts
+Assume the first pts should be this value. The time base is 1 / sample rate.
+This allows for padding/trimming at the start of stream. By default, no
+assumption is made about the first frame's expected pts, so no padding or
+trimming is done. For example, this could be set to 0 to pad the beginning with
+silence if an audio stream starts after the video stream or to trim any samples
+with a negative pts due to encoder delay.
+
+ at end table
+
 @section atempo
 
 Adjust audio tempo.
@@ -1095,300 +882,410 @@ atempo=1.25
 @end example
 @end itemize
 
- at section earwax
+ at section atrim
 
-Make audio easier to listen to on headphones.
+Trim the input so that the output contains one continuous subpart of the input.
 
-This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
-so that when listened to on headphones the stereo image is moved from
-inside your head (standard for headphones) to outside and in front of
-the listener (standard for speakers).
+This filter accepts the following options:
+ at table @option
+ at item start
+Timestamp (in seconds) of the start of the kept section. I.e. the audio sample
+with the timestamp @var{start} will be the first sample in the output.
 
-Ported from SoX.
-
- at section pan
-
-Mix channels with specific gain levels. The filter accepts the output
-channel layout followed by a set of channels definitions.
-
-This filter is also designed to remap efficiently the channels of an audio
-stream.
-
-The filter accepts parameters of the form:
-"@var{l}:@var{outdef}:@var{outdef}:..."
+ at item end
+Timestamp (in seconds) of the first audio sample that will be dropped. I.e. the
+audio sample immediately preceding the one with the timestamp @var{end} will be
+the last sample in the output.
 
- at table @option
- at item l
-output channel layout or number of channels
+ at item start_pts
+Same as @var{start}, except this option sets the start timestamp in samples
+instead of seconds.
 
- at item outdef
-output channel specification, of the form:
-"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
+ at item end_pts
+Same as @var{end}, except this option sets the end timestamp in samples instead
+of seconds.
 
- at item out_name
-output channel to define, either a channel name (FL, FR, etc.) or a channel
-number (c0, c1, etc.)
+ at item duration
+Maximum duration of the output in seconds.
 
- at item gain
-multiplicative coefficient for the channel, 1 leaving the volume unchanged
+ at item start_sample
+Number of the first sample that should be passed to output.
 
- at item in_name
-input channel to use, see out_name for details; it is not possible to mix
-named and numbered input channels
+ at item end_sample
+Number of the first sample that should be dropped.
 @end table
 
-If the `=' in a channel specification is replaced by `<', then the gains for
-that specification will be renormalized so that the total is 1, thus
-avoiding clipping noise.
+Note that the first two sets of the start/end options and the @option{duration}
+option look at the frame timestamp, while the _sample options simply count the
+samples that pass through the filter. So start/end_pts and start/end_sample will
+give different results when the timestamps are wrong, inexact or do not start at
+zero. Also note that this filter does not modify the timestamps. If you wish
+that the output timestamps start at zero, insert the asetpts filter after the
+atrim filter.
 
- at subsection Mixing examples
+If multiple start or end options are set, this filter tries to be greedy and
+keep all samples that match at least one of the specified constraints. To keep
+only the part that matches all the constraints at once, chain multiple atrim
+filters.
 
-For example, if you want to down-mix from stereo to mono, but with a bigger
-factor for the left channel:
+The defaults are such that all the input is kept. So it is possible to set e.g.
+just the end values to keep everything before the specified time.
+
+Examples:
+ at itemize
+ at item
+drop everything except the second minute of input
 @example
-pan=1:c0=0.9*c0+0.1*c1
+ffmpeg -i INPUT -af atrim=60:120
 @end example
 
-A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
-7-channels surround:
+ at item
+keep only the first 1000 samples
 @example
-pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
+ffmpeg -i INPUT -af atrim=end_sample=1000
 @end example
 
-Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
-that should be preferred (see "-ac" option) unless you have very specific
-needs.
+ at end itemize
 
- at subsection Remapping examples
+ at section bandpass
 
-The channel remapping will be effective if, and only if:
+Apply a two-pole Butterworth band-pass filter with central
+frequency @var{frequency}, and (3dB-point) band-width width.
+The @var{csg} option selects a constant skirt gain (peak gain = Q)
+instead of the default: constant 0dB peak gain.
+The filter roll off at 6dB per octave (20dB per decade).
 
- at itemize
- at item gain coefficients are zeroes or ones,
- at item only one input per channel output,
- at end itemize
+The filter accepts the following options:
 
-If all these conditions are satisfied, the filter will notify the user ("Pure
-channel mapping detected"), and use an optimized and lossless method to do the
-remapping.
+ at table @option
+ at item frequency, f
+Set the filter's central frequency. Default is @code{3000}.
 
-For example, if you have a 5.1 source and want a stereo audio stream by
-dropping the extra channels:
- at example
-pan="stereo: c0=FL : c1=FR"
- at end example
+ at item csg
+Constant skirt gain if set to 1. Defaults to 0.
 
-Given the same source, you can also switch front left and front right channels
-and keep the input channel layout:
- at example
-pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
- at end example
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
 
-If the input is a stereo audio stream, you can mute the front left channel (and
-still keep the stereo channel layout) with:
- at example
-pan="stereo:c1=c1"
- at end example
+ at item width, w
+Specify the band-width of a filter in width_type units.
+ at end table
 
-Still with a stereo audio stream input, you can copy the right channel in both
-front left and right:
- at example
-pan="stereo: c0=FR : c1=FR"
- at end example
+ at section bandreject
 
- at section silencedetect
+Apply a two-pole Butterworth band-reject filter with central
+frequency @var{frequency}, and (3dB-point) band-width @var{width}.
+The filter roll off at 6dB per octave (20dB per decade).
 
-Detect silence in an audio stream.
+The filter accepts the following options:
 
-This filter logs a message when it detects that the input audio volume is less
-or equal to a noise tolerance value for a duration greater or equal to the
-minimum detected noise duration.
+ at table @option
+ at item frequency, f
+Set the filter's central frequency. Default is @code{3000}.
 
-The printed times and duration are expressed in seconds.
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
+
+ at item width, w
+Specify the band-width of a filter in width_type units.
+ at end table
+
+ at section bass
+
+Boost or cut the bass (lower) frequencies of the audio using a two-pole
+shelving filter with a response similar to that of a standard
+hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
 
 The filter accepts the following options:
 
 @table @option
- at item duration, d
-Set silence duration until notification (default is 2 seconds).
+ at item gain, g
+Give the gain at 0 Hz. Its useful range is about -20
+(for a large cut) to +20 (for a large boost).
+Beware of clipping when using a positive gain.
 
- at item noise, n
-Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
-specified value) or amplitude ratio. Default is -60dB, or 0.001.
+ at item frequency, f
+Set the filter's central frequency and so can be used
+to extend or reduce the frequency range to be boosted or cut.
+The default value is @code{100} Hz.
+
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
 @end table
 
- at subsection Examples
+ at item width, w
+Determine how steep is the filter's shelf transition.
+ at end table
 
- at itemize
- at item
-Detect 5 seconds of silence with -50dB noise tolerance:
+ at section biquad
+
+Apply a biquad IIR filter with the given coefficients.
+Where @var{b0}, @var{b1}, @var{b2} and @var{a0}, @var{a1}, @var{a2}
+are the numerator and denominator coefficients respectively.
+
+ at section channelmap
+
+Remap input channels to new locations.
+
+This filter accepts the following named parameters:
+ at table @option
+ at item channel_layout
+Channel layout of the output stream.
+
+ at item map
+Map channels from input to output. The argument is a '|'-separated list of
+mappings, each in the @code{@var{in_channel}- at var{out_channel}} or
+ at var{in_channel} form. @var{in_channel} can be either the name of the input
+channel (e.g. FL for front left) or its index in the input channel layout.
+ at var{out_channel} is the name of the output channel or its index in the output
+channel layout. If @var{out_channel} is not given then it is implicitly an
+index, starting with zero and increasing by one for each mapping.
+ at end table
+
+If no mapping is present, the filter will implicitly map input channels to
+output channels preserving index.
+
+For example, assuming a 5.1+downmix input MOV file
 @example
-silencedetect=n=-50dB:d=5
+ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
 @end example
+will create an output WAV file tagged as stereo from the downmix channels of
+the input.
 
- at item
-Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
-tolerance in @file{silence.mp3}:
+To fix a 5.1 WAV improperly encoded in AAC's native channel order
 @example
-ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
+ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
 @end example
- at end itemize
 
- at section asyncts
-Synchronize audio data with timestamps by squeezing/stretching it and/or
-dropping samples/adding silence when needed.
+ at section channelsplit
 
-This filter is not built by default, please use @ref{aresample} to do squeezing/stretching.
+Split each channel in input audio stream into a separate output stream.
 
-The filter accepts the following named parameters:
+This filter accepts the following named parameters:
 @table @option
+ at item channel_layout
+Channel layout of the input stream. Default is "stereo".
+ at end table
 
- at item compensate
-Enable stretching/squeezing the data to make it match the timestamps. Disabled
-by default. When disabled, time gaps are covered with silence.
+For example, assuming a stereo input MP3 file
+ at example
+ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
+ at end example
+will create an output Matroska file with two audio streams, one containing only
+the left channel and the other the right channel.
 
- at item min_delta
-Minimum difference between timestamps and audio data (in seconds) to trigger
-adding/dropping samples. Default value is 0.1. If you get non-perfect sync with
-this filter, try setting this parameter to 0.
+To split a 5.1 WAV file into per-channel files
+ at example
+ffmpeg -i in.wav -filter_complex
+'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
+-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
+front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
+side_right.wav
+ at end example
 
- at item max_comp
-Maximum compensation in samples per second. Relevant only with compensate=1.
-Default value 500.
+ at section earwax
 
- at item first_pts
-Assume the first pts should be this value. The time base is 1 / sample rate.
-This allows for padding/trimming at the start of stream. By default, no
-assumption is made about the first frame's expected pts, so no padding or
-trimming is done. For example, this could be set to 0 to pad the beginning with
-silence if an audio stream starts after the video stream or to trim any samples
-with a negative pts due to encoder delay.
+Make audio easier to listen to on headphones.
 
- at end table
+This filter adds `cues' to 44.1kHz stereo (i.e. audio CD format) audio
+so that when listened to on headphones the stereo image is moved from
+inside your head (standard for headphones) to outside and in front of
+the listener (standard for speakers).
 
- at section atrim
-Trim the input so that the output contains one continuous subpart of the input.
+Ported from SoX.
+
+ at section equalizer
+
+Apply a two-pole peaking equalisation (EQ) filter. With this
+filter, the signal-level at and around a selected frequency can
+be increased or decreased, whilst (unlike bandpass and bandreject
+filters) that at all other frequencies is unchanged.
+
+In order to produce complex equalisation curves, this filter can
+be given several times, each with a different central frequency.
+
+The filter accepts the following options:
 
-This filter accepts the following options:
 @table @option
- at item start
-Timestamp (in seconds) of the start of the kept section. I.e. the audio sample
-with the timestamp @var{start} will be the first sample in the output.
+ at item frequency, f
+Set the filter's central frequency in Hz.
 
- at item end
-Timestamp (in seconds) of the first audio sample that will be dropped. I.e. the
-audio sample immediately preceding the one with the timestamp @var{end} will be
-the last sample in the output.
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
 
- at item start_pts
-Same as @var{start}, except this option sets the start timestamp in samples
-instead of seconds.
+ at item width, w
+Specify the band-width of a filter in width_type units.
 
- at item end_pts
-Same as @var{end}, except this option sets the end timestamp in samples instead
-of seconds.
+ at item gain, g
+Set the required gain or attenuation in dB.
+Beware of clipping when using a positive gain.
+ at end table
 
- at item duration
-Maximum duration of the output in seconds.
+ at section pan
+
+Mix channels with specific gain levels. The filter accepts the output
+channel layout followed by a set of channels definitions.
+
+This filter is also designed to remap efficiently the channels of an audio
+stream.
+
+The filter accepts parameters of the form:
+"@var{l}:@var{outdef}:@var{outdef}:..."
+
+ at table @option
+ at item l
+output channel layout or number of channels
+
+ at item outdef
+output channel specification, of the form:
+"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
+
+ at item out_name
+output channel to define, either a channel name (FL, FR, etc.) or a channel
+number (c0, c1, etc.)
 
- at item start_sample
-Number of the first sample that should be passed to output.
+ at item gain
+multiplicative coefficient for the channel, 1 leaving the volume unchanged
 
- at item end_sample
-Number of the first sample that should be dropped.
+ at item in_name
+input channel to use, see out_name for details; it is not possible to mix
+named and numbered input channels
 @end table
 
-Note that the first two sets of the start/end options and the @option{duration}
-option look at the frame timestamp, while the _sample options simply count the
-samples that pass through the filter. So start/end_pts and start/end_sample will
-give different results when the timestamps are wrong, inexact or do not start at
-zero. Also note that this filter does not modify the timestamps. If you wish
-that the output timestamps start at zero, insert the asetpts filter after the
-atrim filter.
-
-If multiple start or end options are set, this filter tries to be greedy and
-keep all samples that match at least one of the specified constraints. To keep
-only the part that matches all the constraints at once, chain multiple atrim
-filters.
+If the `=' in a channel specification is replaced by `<', then the gains for
+that specification will be renormalized so that the total is 1, thus
+avoiding clipping noise.
 
-The defaults are such that all the input is kept. So it is possible to set e.g.
-just the end values to keep everything before the specified time.
+ at subsection Mixing examples
 
-Examples:
- at itemize
- at item
-drop everything except the second minute of input
+For example, if you want to down-mix from stereo to mono, but with a bigger
+factor for the left channel:
 @example
-ffmpeg -i INPUT -af atrim=60:120
+pan=1:c0=0.9*c0+0.1*c1
 @end example
 
- at item
-keep only the first 1000 samples
+A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
+7-channels surround:
 @example
-ffmpeg -i INPUT -af atrim=end_sample=1000
+pan=stereo: FL < FL + 0.5*FC + 0.6*BL + 0.6*SL : FR < FR + 0.5*FC + 0.6*BR + 0.6*SR
 @end example
 
+Note that @command{ffmpeg} integrates a default down-mix (and up-mix) system
+that should be preferred (see "-ac" option) unless you have very specific
+needs.
+
+ at subsection Remapping examples
+
+The channel remapping will be effective if, and only if:
+
+ at itemize
+ at item gain coefficients are zeroes or ones,
+ at item only one input per channel output,
 @end itemize
 
- at section channelsplit
-Split each channel in input audio stream into a separate output stream.
+If all these conditions are satisfied, the filter will notify the user ("Pure
+channel mapping detected"), and use an optimized and lossless method to do the
+remapping.
 
-This filter accepts the following named parameters:
- at table @option
- at item channel_layout
-Channel layout of the input stream. Default is "stereo".
- at end table
+For example, if you have a 5.1 source and want a stereo audio stream by
+dropping the extra channels:
+ at example
+pan="stereo: c0=FL : c1=FR"
+ at end example
 
-For example, assuming a stereo input MP3 file
+Given the same source, you can also switch front left and front right channels
+and keep the input channel layout:
 @example
-ffmpeg -i in.mp3 -filter_complex channelsplit out.mkv
+pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
 @end example
-will create an output Matroska file with two audio streams, one containing only
-the left channel and the other the right channel.
 
-To split a 5.1 WAV file into per-channel files
+If the input is a stereo audio stream, you can mute the front left channel (and
+still keep the stereo channel layout) with:
 @example
-ffmpeg -i in.wav -filter_complex
-'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'
--map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'
-front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
-side_right.wav
+pan="stereo:c1=c1"
 @end example
 
- at section channelmap
-Remap input channels to new locations.
+Still with a stereo audio stream input, you can copy the right channel in both
+front left and right:
+ at example
+pan="stereo: c0=FR : c1=FR"
+ at end example
 
-This filter accepts the following named parameters:
- at table @option
- at item channel_layout
-Channel layout of the output stream.
+ at section highpass
 
- at item map
-Map channels from input to output. The argument is a '|'-separated list of
-mappings, each in the @code{@var{in_channel}- at var{out_channel}} or
- at var{in_channel} form. @var{in_channel} can be either the name of the input
-channel (e.g. FL for front left) or its index in the input channel layout.
- at var{out_channel} is the name of the output channel or its index in the output
-channel layout. If @var{out_channel} is not given then it is implicitly an
-index, starting with zero and increasing by one for each mapping.
- at end table
+Apply a high-pass filter with 3dB point frequency.
+The filter can be either single-pole, or double-pole (the default).
+The filter roll off at 6dB per pole per octave (20dB per pole per decade).
 
-If no mapping is present, the filter will implicitly map input channels to
-output channels preserving index.
+The filter accepts the following options:
 
-For example, assuming a 5.1+downmix input MOV file
- at example
-ffmpeg -i in.mov -filter 'channelmap=map=DL-FL|DR-FR' out.wav
- at end example
-will create an output WAV file tagged as stereo from the downmix channels of
-the input.
+ at table @option
+ at item frequency, f
+Set frequency in Hz. Default is 3000.
 
-To fix a 5.1 WAV improperly encoded in AAC's native channel order
- at example
-ffmpeg -i in.wav -filter 'channelmap=1|2|0|5|3|4:channel_layout=5.1' out.wav
- at end example
+ at item poles, p
+Set number of poles. Default is 2.
+
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
+
+ at item width, w
+Specify the band-width of a filter in width_type units.
+Applies only to double-pole filter.
+The default is 0.707q and gives a Butterworth response.
+ at end table
 
 @section join
+
 Join multiple input streams into one multi-channel stream.
 
 The filter accepts the following named parameters:
@@ -1425,10 +1322,119 @@ ffmpeg -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex
 out
 @end example
 
+ at section lowpass
+
+Apply a low-pass filter with 3dB point frequency.
+The filter can be either single-pole or double-pole (the default).
+The filter roll off at 6dB per pole per octave (20dB per pole per decade).
+
+The filter accepts the following options:
+
+ at table @option
+ at item frequency, f
+Set frequency in Hz. Default is 500.
+
+ at item poles, p
+Set number of poles. Default is 2.
+
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
+
+ at item width, w
+Specify the band-width of a filter in width_type units.
+Applies only to double-pole filter.
+The default is 0.707q and gives a Butterworth response.
+ at end table
+
 @section resample
+
 Convert the audio sample format, sample rate and channel layout. This filter is
 not meant to be used directly.
 
+ at section silencedetect
+
+Detect silence in an audio stream.
+
+This filter logs a message when it detects that the input audio volume is less
+or equal to a noise tolerance value for a duration greater or equal to the
+minimum detected noise duration.
+
+The printed times and duration are expressed in seconds.
+
+The filter accepts the following options:
+
+ at table @option
+ at item duration, d
+Set silence duration until notification (default is 2 seconds).
+
+ at item noise, n
+Set noise tolerance. Can be specified in dB (in case "dB" is appended to the
+specified value) or amplitude ratio. Default is -60dB, or 0.001.
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Detect 5 seconds of silence with -50dB noise tolerance:
+ at example
+silencedetect=n=-50dB:d=5
+ at end example
+
+ at item
+Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
+tolerance in @file{silence.mp3}:
+ at example
+ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
+ at end example
+ at end itemize
+
+ at section treble
+
+Boost or cut treble (upper) frequencies of the audio using a two-pole
+shelving filter with a response similar to that of a standard
+hi-fi's tone-controls. This is also known as shelving equalisation (EQ).
+
+The filter accepts the following options:
+
+ at table @option
+ at item gain, g
+Give the gain at whichever is the lower of ~22 kHz and the
+Nyquist frequency. Its useful range is about -20 (for a large cut)
+to +20 (for a large boost). Beware of clipping when using a positive gain.
+
+ at item frequency, f
+Set the filter's central frequency and so can be used
+to extend or reduce the frequency range to be boosted or cut.
+The default value is @code{3000} Hz.
+
+ at item width_type
+Set method to specify band-width of filter.
+ at table @option
+ at item h
+Hz
+ at item q
+Q-Factor
+ at item o
+octave
+ at item s
+slope
+ at end table
+
+ at item width, w
+Determine how steep is the filter's shelf transition.
+ at end table
+
 @section volume
 
 Adjust the input audio volume.
-- 
1.7.9.5



More information about the ffmpeg-devel mailing list