libavcodec/acelp_filters.h

   1 /*
   2  * various filters for ACELP-based codecs
   3  *
   4  * Copyright (c) 2008 Vladimir Voroshilov
   5  *
   6  * This file is part of FFmpeg.
   7  *
   8  * FFmpeg is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2.1 of the License, or (at your option) any later version.
  12  *
  13  * FFmpeg is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Lesser General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with FFmpeg; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  21  */
  22
  23 #ifndef FFMPEG_ACELP_FILTERS_H
  24 #define FFMPEG_ACELP_FILTERS_H
  25
  26 #include <stdint.h>
  27
  28 /**
  29  * low-pass FIR (Finite Impulse Response) filter coefficients
  30  *
  31  *   A similar filter is named b30 in G.729.
  32  *
  33  *   G.729 specification says:
  34  *     b30 is based on Hamming windowed sinc functions, truncated at +/-29 and
  35  *     padded with zeros at +/-30 b30[30]=0.
  36  *     The filter has a cut-off frequency (-3 dB) at 3600 Hz in the oversampled
  37  *     domain.
  38  *
  39  *   After some analysis, I found this approximation:
  40  *
  41  *                                    PI * x
  42  *   Hamm(x,N) = 0.53836-0.46164*cos(--------)
  43  *                                      N-1
  44  *                                      ---
  45  *                                       2
  46  *
  47  *                                                             PI * x
  48  *   Hamm'(x,k) = Hamm(x - k, 2*k+1) =  0.53836 + 0.46164*cos(--------)
  49  *                                                                k
  50  *
  51  *             sin(PI * x)
  52  *   Sinc(x) = ----------- (normalized sinc function)
  53  *               PI * x
  54  *
  55  *   h(t,B) = 2 * B * Sinc(2 * B * t) (impulse response of sinc low-pass filter)
  56  *
  57  *   b(k,B, n) = Hamm'(n, k) * h(n, B)
  58  *
  59  *
  60  *       3600
  61  *   B = ----
  62  *       8000
  63  *
  64  *   3600 - cut-off frequency
  65  *   8000 - sampling rate
  66  *   k    - filter order
  67  *
  68  *   ff_acelp_interp_filter[6*i+j] = b(10, 3600/8000, i+j/6)
  69  *
  70  * The filter assumes the following order of fractions (X - integer delay):
  71  *
  72  * 1/3 precision: X     1/3      2/3      X     1/3      2/3      X
  73  * 1/6 precision: X 1/6 2/6 3/6  4/6  5/6 X 1/6 2/6 3/6  4/6  5/6 X
  74  *
  75  * The filter can be used for 1/3 precision, too, by
  76  * passing 2*pitch_delay_frac as third parameter to the interpolation routine.
  77  *
  78  */
  79 extern const int16_t ff_acelp_interp_filter[61];
  80
  81 /**
  82  * \brief Generic interpolation routine
  83  * \param out [out] buffer for interpolated data
  84  * \param in input data
  85  * \param filter_coeffs interpolation filter coefficients (0.15)
  86  * \param precision filter is able to interpolate with 1/precision precision of pitch delay
  87  * \param pitch_delay_frac pitch delay, fractional part [0..precision-1]
  88  * \param filter_length filter length
  89  * \param length length of speech data to process
  90  *
  91  * filter_coeffs contains coefficients of the positive half of the symmetric
  92  * interpolation filter. filter_coeffs[0] should the central (unpaired) coefficient.
  93  * See ff_acelp_interp_filter fot example.
  94  *
  95  */
  96 void ff_acelp_interpolate(
  97         int16_t* out,
  98         const int16_t* in,
  99         const int16_t* filter_coeffs,
 100         int precision,
 101         int pitch_delay_frac,
 102         int filter_length,
 103         int length);
 104
 105 /**
 106  * \brief Circularly convolve fixed vector with a phase dispersion impulse
 107  *        response filter (D.6.2 of G.729 and 6.1.5 of AMR).
 108  * \param fc_out vector with filter applied
 109  * \param fc_in source vector
 110  * \param filter phase filter coefficients
 111  *
 112  *  fc_out[n] = sum(i,0,len-1){ fc_in[i] * filter[(len + n - i)%len] }
 113  *
 114  * \note fc_in and fc_out should not overlap!
 115  */
 116 void ff_acelp_convolve_circ(
 117         int16_t* fc_out,
 118         const int16_t* fc_in,
 119         const int16_t* filter,
 120         int subframe_size);
 121
 122 /**
 123  * \brief LP synthesis filter
 124  * \param out [out] pointer to output buffer
 125  * \param filter_coeffs filter coefficients (-0x8000 <= (3.12) < 0x8000)
 126  * \param in input signal
 127  * \param buffer_length amount of data to process
 128  * \param filter_length filter length (11 for 10th order LP filter)
 129  * \param stop_on_overflow   1 - return immediately if overflow occurs
 130  *                           0 - ignore overflows
 131  * \param rounder the amount to add for rounding (usually 0x800 or 0xfff)
 132  *
 133  * \return 1 if overflow occurred, 0 - otherwise
 134  *
 135  * \note Output buffer must contain 10 samples of past
 136  *       speech data before pointer.
 137  *
 138  * Routine applies 1/A(z) filter to given speech data.
 139  */
 140 int ff_acelp_lp_synthesis_filter(
 141         int16_t *out,
 142         const int16_t* filter_coeffs,
 143         const int16_t* in,
 144         int buffer_length,
 145         int filter_length,
 146         int stop_on_overflow,
 147         int rounder);
 148
 149 /**
 150  * \brief Calculates coefficients of weighted A(z/weight) filter.
 151  * \param out [out] weighted A(z/weight) result
 152  *                  filter (-0x8000 <= (3.12) < 0x8000)
 153  * \param in source filter (-0x8000 <= (3.12) < 0x8000)
 154  * \param weight_pow array containing weight^i (-0x8000 <= (0.15) < 0x8000)
 155  * \param filter_length filter length (11 for 10th order LP filter)
 156  *
 157  * out[i]=weight_pow[i]*in[i] , i=0..9
 158  */
 159 void ff_acelp_weighted_filter(
 160         int16_t *out,
 161         const int16_t* in,
 162         const int16_t *weight_pow,
 163         int filter_length);
 164
 165 /**
 166  * \brief high-pass filtering and upscaling (4.2.5 of G.729)
 167  * \param out [out] output buffer for filtered speech data
 168  * \param hpf_f [in/out] past filtered data from previous (2 items long)
 169  *                       frames (-0x20000000 <= (14.13) < 0x20000000)
 170  * \param in speech data to process
 171  * \param length input data size
 172  *
 173  * out[i] = 0.93980581 * in[i] - 1.8795834 * in[i-1] + 0.93980581 * in[i-2] +
 174  *          1.9330735 * out[i-1] - 0.93589199 * out[i-2]
 175  *
 176  * The filter has a cut-off frequency of 100Hz
 177  *
 178  * \note Two items before the top of the out buffer must contain two items from the
 179  *       tail of the previous subframe.
 180  *
 181  * \remark It is safe to pass the same array in in and out parameters.
 182  *
 183  * \remark AMR uses mostly the same filter (cut-off frequency 60Hz, same formula,
 184  *         but constants differs in 5th sign after comma). Fortunately in
 185  *         fixed-point all coefficients are the same as in G.729. Thus this
 186  *         routine can be used for the fixed-point AMR decoder, too.
 187  */
 188 void ff_acelp_high_pass_filter(
 189         int16_t* out,
 190         int hpf_f[2],
 191         const int16_t* in,
 192         int length);
 193
 194 #endif /* FFMPEG_ACELP_FILTERS_H */