[FFmpeg-devel] [PATCH] lavfi: add compand filter

[Lou Logan]

Greetings Kahn,

This is only a review of the documentation.

On Thu, 25 Jul 2013 13:24:58 +0000, Paul B Mahol wrote:

> Signed-off-by: Paul B Mahol <onemda at gmail.com>
> ---
>  doc/filters.texi         |  48 +++++
>  libavfilter/Makefile     |   1 +
>  libavfilter/af_compand.c | 514 +++++++++++++++++++++++++++++++++++++++++++++++
>  libavfilter/allfilters.c |   1 +
>  4 files changed, 564 insertions(+)
>  create mode 100644 libavfilter/af_compand.c
> 
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 0c18446..080c598 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -1176,6 +1176,54 @@ front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'
>  side_right.wav
>  @end example
>  
> + at section compand
> +
> +Compress or expand the dynamic range of the audio.

Suggested alternative:
Compress or expand audio dynamic range.

> +
> +A description of the accepted parameters follows.
> +
> + at table @option
> + at item attacks

Maybe a description should go here because users may not notice that the
sentences below also apply to this option and thus may believe it is
undocumented.

> + at item decays
> +Set list of times in seconds for each channel over which the instantaneous level
> +of the input signal is averaged to determine its volume.
> + at option{attacks} refer to increase of volume and @option{decays} to decrease of
> +volume.

+ at option{attacks} refers to increase of volume, and @option{decays} refers to
+decrease of volume.

> +For most situations, tha attack time (response to the music getting louder)

typo: s/tha/the
nit: s/music/audio

> +should be shorter than the decay time because the human ear is more sensitive
> +to sudden loud music than sudden soft music.

nit: s/music/audio

> +Typical value for attack is 0.3 seconds and for decay 0.8 seconds.

Where do these values come from? Are there default values?

> + at item points
> +Set list of points for tranfer function, specified in dB relative to maximum possible

typo: s/tranfer/transfer

> +signal amplitued.

typo: s/amplitued/amplitude

> +The input values must be in strictly increasing order but the transfer function does
> +not have to me monotonically rising. The point 0/0 is assumed but may be overriden

typo: s/me/be
typo: s/overriden/overridden

> +(by 0\out-dBn). Typical values for the transfer function are @code{-70\-60|-20\0}.
> +
> + at item soft-knee
> +Set amount for which the points at where adjacent line segments on the transfer function meet will be rounded.

nit: line break needed

Is there a default value?

> +
> + at item gain
> +Set additional gain in dB to be applied at all points on the transfer function
> +and allows easy adjustment of the overall gain.
> +Default is @code{0}.
> +
> + at item volume
> +Set initial volume in dB to be assumed for each channel when filtering starts.
> +This permits the user to supply a nominal level initially, so that, for example,
> +a very large gain is not applied to initial signal levels before the companding
> +has begun to operates. A typical value, for audio which is initially quiet is -90 dB.

typo: s/operates/operate

Also remove the comma after "A typical value".

> +Default is @code{0}.
> +
> + at item delay
> +Set delay in seconds. Default is @code{0}. The input audio
> +is analysed immediately, but is delayed before being fed to the
> +volume adjuster. Specifying a delay approximately equal to the attack/decay
> +times allow the filter to effectively operate in predictive rather than
> +reactive mode.
> + at end table
> +

Missing example(s).

[...]

> +AVFilter avfilter_af_compand = {
> +    .name          = "compand",
> +    .description   = NULL_IF_CONFIG_SMALL("Compress or expand the dynamic range of the audio."),

Suggested alternative:
Compress or expand audio dynamic range.

Thanks.

Lou