Merge commit 'a49aa440c939e221194f8d95bf98673f8cf38a06'
authorMichael Niedermayer <michaelni@gmx.at>
Fri, 4 Apr 2014 22:16:53 +0000 (00:16 +0200)
committerMichael Niedermayer <michaelni@gmx.at>
Fri, 4 Apr 2014 22:16:53 +0000 (00:16 +0200)
* commit 'a49aa440c939e221194f8d95bf98673f8cf38a06':
  af_volume: implement replaygain pre-amplification

Conflicts:
doc/filters.texi

Merged-by: Michael Niedermayer <michaelni@gmx.at>
1  2 
doc/filters.texi
libavfilter/af_volume.c
libavfilter/af_volume.h

@@@ -1475,454 -577,264 +1475,459 @@@ ffmpeg -i fl -i fr -i fc -i sl -i sr -
  out
  @end example
  
 -@section resample
 -Convert the audio sample format, sample rate and channel layout. This filter is
 -not meant to be used directly, it is inserted automatically by libavfilter
 -whenever conversion is needed. Use the @var{aformat} filter to force a specific
 -conversion.
 +@section ladspa
  
 -@section volume
 +Load a LADSPA (Linux Audio Developer's Simple Plugin API) plugin.
  
 -Adjust the input audio volume.
 +To enable compilation of this filter you need to configure FFmpeg with
 +@code{--enable-ladspa}.
  
 -The filter accepts the following named parameters:
  @table @option
 +@item file, f
 +Specifies the name of LADSPA plugin library to load. If the environment
 +variable @env{LADSPA_PATH} is defined, the LADSPA plugin is searched in
 +each one of the directories specified by the colon separated list in
 +@env{LADSPA_PATH}, otherwise in the standard LADSPA paths, which are in
 +this order: @file{HOME/.ladspa/lib/}, @file{/usr/local/lib/ladspa/},
 +@file{/usr/lib/ladspa/}.
 +
 +@item plugin, p
 +Specifies the plugin within the library. Some libraries contain only
 +one plugin, but others contain many of them. If this is not set filter
 +will list all available plugins within the specified library.
 +
 +@item controls, c
 +Set the '|' separated list of controls which are zero or more floating point
 +values that determine the behavior of the loaded plugin (for example delay,
 +threshold or gain).
 +Controls need to be defined using the following syntax:
 +c0=@var{value0}|c1=@var{value1}|c2=@var{value2}|..., where
 +@var{valuei} is the value set on the @var{i}-th control.
 +If @option{controls} is set to @code{help}, all available controls and
 +their valid ranges are printed.
 +
 +@item sample_rate, s
 +Specify the sample rate, default to 44100. Only used if plugin have
 +zero inputs.
 +
 +@item nb_samples, n
 +Set the number of samples per channel per each output frame, default
 +is 1024. Only used if plugin have zero inputs.
 +
 +@item duration, d
 +Set the minimum duration of the sourced audio. See the function
 +@code{av_parse_time()} for the accepted format, also check the "Time duration"
 +section in the ffmpeg-utils manual.
 +Note that the resulting duration may be greater than the specified duration,
 +as the generated audio is always cut at the end of a complete frame.
 +If not specified, or the expressed duration is negative, the audio is
 +supposed to be generated forever.
 +Only used if plugin have zero inputs.
  
 -@item volume
 -Expresses how the audio volume will be increased or decreased.
 +@end table
  
 -Output values are clipped to the maximum value.
 +@subsection Examples
  
 -The output audio volume is given by the relation:
 +@itemize
 +@item
 +List all available plugins within amp (LADSPA example plugin) library:
  @example
 -@var{output_volume} = @var{volume} * @var{input_volume}
 +ladspa=file=amp
  @end example
  
 -Default value for @var{volume} is 1.0.
 +@item
 +List all available controls and their valid ranges for @code{vcf_notch}
 +plugin from @code{VCF} library:
 +@example
 +ladspa=f=vcf:p=vcf_notch:c=help
 +@end example
  
 -@item precision
 -Mathematical precision.
 +@item
 +Simulate low quality audio equipment using @code{Computer Music Toolkit} (CMT)
 +plugin library:
 +@example
 +ladspa=file=cmt:plugin=lofi:controls=c0=22|c1=12|c2=12
 +@end example
  
 -This determines which input sample formats will be allowed, which affects the
 -precision of the volume scaling.
 +@item
 +Add reverberation to the audio using TAP-plugins
 +(Tom's Audio Processing plugins):
 +@example
 +ladspa=file=tap_reverb:tap_reverb
 +@end example
  
 -@table @option
 -@item fixed
 -8-bit fixed-point; limits input sample format to U8, S16, and S32.
 -@item float
 -32-bit floating-point; limits input sample format to FLT. (default)
 -@item double
 -64-bit floating-point; limits input sample format to DBL.
 -@end table
 +@item
 +Generate white noise, with 0.2 amplitude:
 +@example
 +ladspa=file=cmt:noise_source_white:c=c0=.2
 +@end example
  
 -@item replaygain
 -Behaviour on encountering ReplayGain side data in input frames.
 +@item
 +Generate 20 bpm clicks using plugin @code{C* Click - Metronome} from the
 +@code{C* Audio Plugin Suite} (CAPS) library:
 +@example
 +ladspa=file=caps:Click:c=c1=20'
 +@end example
  
 +@item
 +Apply @code{C* Eq10X2 - Stereo 10-band equaliser} effect:
 +@example
 +ladspa=caps:Eq10X2:c=c0=-48|c9=-24|c3=12|c4=2
 +@end example
 +@end itemize
 +
 +@subsection Commands
 +
 +This filter supports the following commands:
  @table @option
 -@item drop
 -Remove ReplayGain side data, ignoring its contents (the default).
 +@item cN
 +Modify the @var{N}-th control value.
  
 -@item ignore
 -Ignore ReplayGain side data, but leave it in the frame.
 +If the specified value is not valid, it is ignored and prior one is kept.
 +@end table
  
 -@item track
 -Prefer track gain, if present.
 +@section lowpass
  
 -@item album
 -Prefer album gain, if present.
 +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:
 +
 +@table @option
 +@item frequency, f
 +Set frequency in Hz. Default is 500.
 +
 +@item poles, p
 +Set number of poles. Default is 2.
 +
 +@item width_type
 +Set method to specify band-width of filter.
 +@table @option
 +@item h
 +Hz
 +@item q
 +Q-Factor
 +@item o
 +octave
 +@item s
 +slope
  @end table
  
 -@item replaygain_preamp
 -Pre-amplification gain in dB to apply to the selected replaygain gain.
 +@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
  
 -Default value for @var{replaygain_preamp} is 0.0.
 +@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}:..."
 +
 +@table @option
 +@item l
 +output channel layout or number of channels
 +
 +@item outdef
 +output channel specification, of the form:
 +"@var{out_name}=[@var{gain}*]@var{in_name}[+[@var{gain}*]@var{in_name}...]"
 +
 +@item out_name
 +output channel to define, either a channel name (FL, FR, etc.) or a channel
 +number (c0, c1, etc.)
 +
 +@item gain
 +multiplicative coefficient for the channel, 1 leaving the volume unchanged
  
 +@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
  
 -@subsection Examples
 +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.
  
 -@itemize
 -@item
 -Halve the input audio volume:
 +@subsection Mixing examples
 +
 +For example, if you want to down-mix from stereo to mono, but with a bigger
 +factor for the left channel:
  @example
 -volume=volume=0.5
 -volume=volume=1/2
 -volume=volume=-6.0206dB
 +pan=1:c0=0.9*c0+0.1*c1
  @end example
  
 -@item
 -Increase input audio power by 6 decibels using fixed-point precision:
 +A customized down-mix to stereo that works automatically for 3-, 4-, 5- and
 +7-channels surround:
  @example
 -volume=volume=6dB:precision=fixed
 +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.
 +
 +@subsection Remapping examples
 +
 +The channel remapping will be effective if, and only if:
 +
 +@itemize
 +@item gain coefficients are zeroes or ones,
 +@item only one input per channel output,
  @end itemize
  
 -@c man end AUDIO FILTERS
 +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.
  
 -@chapter Audio Sources
 -@c man begin AUDIO SOURCES
 +For example, if you have a 5.1 source and want a stereo audio stream by
 +dropping the extra channels:
 +@example
 +pan="stereo: c0=FL : c1=FR"
 +@end example
  
 -Below is a description of the currently available audio sources.
 +Given the same source, you can also switch front left and front right channels
 +and keep the input channel layout:
 +@example
 +pan="5.1: c0=c1 : c1=c0 : c2=c2 : c3=c3 : c4=c4 : c5=c5"
 +@end example
  
 -@section anullsrc
 +If the input is a stereo audio stream, you can mute the front left channel (and
 +still keep the stereo channel layout) with:
 +@example
 +pan="stereo:c1=c1"
 +@end example
  
 -Null audio source, never return audio frames. It is mainly useful as a
 -template and to be employed in analysis / debugging tools.
 +Still with a stereo audio stream input, you can copy the right channel in both
 +front left and right:
 +@example
 +pan="stereo: c0=FR : c1=FR"
 +@end example
  
 -It accepts as optional parameter a string of the form
 -@var{sample_rate}:@var{channel_layout}.
 +@section replaygain
  
 -@var{sample_rate} specify the sample rate, and defaults to 44100.
 +ReplayGain scanner filter. This filter takes an audio stream as an input and
 +outputs it unchanged.
 +At end of filtering it displays @code{track_gain} and @code{track_peak}.
  
 -@var{channel_layout} specify the channel layout, and can be either an
 -integer or a string representing a channel layout. The default value
 -of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.
 +@section resample
  
 -Check the channel_layout_map definition in
 -@file{libavutil/channel_layout.c} for the mapping between strings and
 -channel layout values.
 +Convert the audio sample format, sample rate and channel layout. This filter is
 +not meant to be used directly.
  
 -Follow some examples:
 -@example
 -#  set the sample rate to 48000 Hz and the channel layout to CH_LAYOUT_MONO.
 -anullsrc=48000:4
 +@section silencedetect
  
 -# same as
 -anullsrc=48000:mono
 -@end example
 +Detect silence in an audio stream.
  
 -@section abuffer
 -Buffer audio frames, and make them available to the filter chain.
 +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.
  
 -This source is not intended to be part of user-supplied graph descriptions but
 -for insertion by calling programs through the interface defined in
 -@file{libavfilter/buffersrc.h}.
 +The printed times and duration are expressed in seconds.
 +
 +The filter accepts the following options:
  
 -It accepts the following named parameters:
  @table @option
 +@item duration, d
 +Set silence duration until notification (default is 2 seconds).
  
 -@item time_base
 -Timebase which will be used for timestamps of submitted frames. It must be
 -either a floating-point number or in @var{numerator}/@var{denominator} form.
 +@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.
 +@end table
  
 -@item sample_rate
 -Audio sample rate.
 +@subsection Examples
  
 -@item sample_fmt
 -Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.
 +@itemize
 +@item
 +Detect 5 seconds of silence with -50dB noise tolerance:
 +@example
 +silencedetect=n=-50dB:d=5
 +@end example
  
 -@item channel_layout
 -Channel layout of the audio data, in the form that can be accepted by
 -@code{av_get_channel_layout()}.
 -@end table
 +@item
 +Complete example with @command{ffmpeg} to detect silence with 0.0001 noise
 +tolerance in @file{silence.mp3}:
 +@example
 +ffmpeg -i silence.mp3 -af silencedetect=noise=0.0001 -f null -
 +@end example
 +@end itemize
  
 -All the parameters need to be explicitly defined.
 +@section treble
  
 -@c man end AUDIO SOURCES
 +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).
  
 -@chapter Audio Sinks
 -@c man begin AUDIO SINKS
 +The filter accepts the following options:
  
 -Below is a description of the currently available audio sinks.
 +@table @option
 +@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.
 +
 +@item width_type
 +Set method to specify band-width of filter.
 +@table @option
 +@item h
 +Hz
 +@item q
 +Q-Factor
 +@item o
 +octave
 +@item s
 +slope
 +@end table
  
 -@section anullsink
 +@item width, w
 +Determine how steep is the filter's shelf transition.
 +@end table
  
 -Null audio sink, do absolutely nothing with the input audio. It is
 -mainly useful as a template and to be employed in analysis / debugging
 -tools.
 +@section volume
  
 -@section abuffersink
 -This sink is intended for programmatic use. Frames that arrive on this sink can
 -be retrieved by the calling program using the interface defined in
 -@file{libavfilter/buffersink.h}.
 +Adjust the input audio volume.
  
 -This filter accepts no parameters.
 +The filter accepts the following options:
  
 -@c man end AUDIO SINKS
 +@table @option
  
 -@chapter Video Filters
 -@c man begin VIDEO FILTERS
 +@item volume
 +Set audio volume expression.
  
 -When you configure your Libav build, you can disable any of the
 -existing filters using --disable-filters.
 -The configure output will show the video filters included in your
 -build.
 +Output values are clipped to the maximum value.
  
 -Below is a description of the currently available video filters.
 +The output audio volume is given by the relation:
 +@example
 +@var{output_volume} = @var{volume} * @var{input_volume}
 +@end example
  
 -@section blackframe
 +Default value for @var{volume} is "1.0".
  
 -Detect frames that are (almost) completely black. Can be useful to
 -detect chapter transitions or commercials. Output lines consist of
 -the frame number of the detected frame, the percentage of blackness,
 -the position in the file if known or -1 and the timestamp in seconds.
 +@item precision
 +Set the mathematical precision.
  
 -In order to display the output lines, you need to set the loglevel at
 -least to the AV_LOG_INFO value.
 +This determines which input sample formats will be allowed, which affects the
 +precision of the volume scaling.
  
 -The filter accepts the following options:
 +@table @option
 +@item fixed
 +8-bit fixed-point; limits input sample format to U8, S16, and S32.
 +@item float
 +32-bit floating-point; limits input sample format to FLT. (default)
 +@item double
 +64-bit floating-point; limits input sample format to DBL.
 +@end table
 +
 +@item replaygain
 +Behaviour on encountering ReplayGain side data in input frames.
  
  @table @option
 +@item drop
 +Remove ReplayGain side data, ignoring its contents (the default).
  
 -@item amount
 -The percentage of the pixels that have to be below the threshold, defaults to
 -98.
 +@item ignore
 +Ignore ReplayGain side data, but leave it in the frame.
  
 -@item threshold
 -Threshold below which a pixel value is considered black, defaults to 32.
 +@item track
 +Prefer track gain, if present.
  
 +@item album
 +Prefer album gain, if present.
  @end table
  
 -@section boxblur
++@item replaygain_preamp
++Pre-amplification gain in dB to apply to the selected replaygain gain.
 -Apply boxblur algorithm to the input video.
++Default value for @var{replaygain_preamp} is 0.0.
 -This filter accepts the following options:
 +@item eval
 +Set when the volume expression is evaluated.
  
 -@table @option
 +It accepts the following values:
 +@table @samp
 +@item once
 +only evaluate expression once during the filter initialization, or
 +when the @samp{volume} command is sent
  
 -@item luma_radius
 -@item luma_power
 -@item chroma_radius
 -@item chroma_power
 -@item alpha_radius
 -@item alpha_power
 +@item frame
 +evaluate expression for each incoming frame
 +@end table
  
 +Default value is @samp{once}.
  @end table
  
 -Chroma and alpha parameters are optional, if not specified they default
 -to the corresponding values set for @var{luma_radius} and
 -@var{luma_power}.
 +The volume expression can contain the following parameters.
  
 -@var{luma_radius}, @var{chroma_radius}, and @var{alpha_radius} represent
 -the radius in pixels of the box used for blurring the corresponding
 -input plane. They are expressions, and can contain the following
 -constants:
  @table @option
 -@item w, h
 -the input width and height in pixels
 +@item n
 +frame number (starting at zero)
 +@item nb_channels
 +number of channels
 +@item nb_consumed_samples
 +number of samples consumed by the filter
 +@item nb_samples
 +number of samples in the current frame
 +@item pos
 +original frame position in the file
 +@item pts
 +frame PTS
 +@item sample_rate
 +sample rate
 +@item startpts
 +PTS at start of stream
 +@item startt
 +time at start of stream
 +@item t
 +frame time
 +@item tb
 +timestamp timebase
 +@item volume
 +last set volume value
 +@end table
  
 -@item cw, ch
 -the input chroma image width and height in pixels
 +Note that when @option{eval} is set to @samp{once} only the
 +@var{sample_rate} and @var{tb} variables are available, all other
 +variables will evaluate to NAN.
  
 -@item hsub, vsub
 -horizontal and vertical chroma subsample values. For example for the
 -pixel format "yuv422p" @var{hsub} is 2 and @var{vsub} is 1.
 -@end table
 +@subsection Commands
  
 -The radius must be a non-negative number, and must not be greater than
 -the value of the expression @code{min(w,h)/2} for the luma and alpha planes,
 -and of @code{min(cw,ch)/2} for the chroma planes.
 +This filter supports the following commands:
 +@table @option
 +@item volume
 +Modify the volume expression.
 +The command accepts the same syntax of the corresponding option.
  
 -@var{luma_power}, @var{chroma_power}, and @var{alpha_power} represent
 -how many times the boxblur filter is applied to the corresponding
 -plane.
 +If the specified expression is not valid, it is kept at its current
 +value.
 +@end table
  
 -Some examples follow:
 +@subsection Examples
  
  @itemize
 -
  @item
 -Apply a boxblur filter with luma, chroma, and alpha radius
 -set to 2:
 +Halve the input audio volume:
  @example
 -boxblur=luma_radius=2:luma_power=1
 +volume=volume=0.5
 +volume=volume=1/2
 +volume=volume=-6.0206dB
  @end example
  
 -@item
 -Set luma radius to 2, alpha and chroma radius to 0
 +In all the above example the named key for @option{volume} can be
 +omitted, for example like in:
  @example
 -boxblur=2:1:0:0:0:0
 +volume=0.5
  @end example
  
  @item
Simple merge
@@@ -69,12 -46,8 +69,13 @@@ typedef struct VolumeContext 
      const AVClass *class;
      AVFloatDSPContext fdsp;
      enum PrecisionType precision;
 +    enum EvalMode eval_mode;
 +    const char *volume_expr;
 +    AVExpr *volume_pexpr;
 +    double var_values[VAR_VARS_NB];
 +
      enum ReplayGainType replaygain;
+     double replaygain_preamp;
      double volume;
      int    volume_i;
      int    channels;