Home | History | Annotate | Download | only in include
      1 /*
      2  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
      3  *
      4  *  Use of this source code is governed by a BSD-style license
      5  *  that can be found in the LICENSE file in the root of the source
      6  *  tree. An additional intellectual property rights grant can be found
      7  *  in the file PATENTS.  All contributing project authors may
      8  *  be found in the AUTHORS file in the root of the source tree.
      9  */
     10 
     11 #ifndef WEBRTC_MODULES_AUDIO_PROCESSING_AGC_INCLUDE_GAIN_CONTROL_H_
     12 #define WEBRTC_MODULES_AUDIO_PROCESSING_AGC_INCLUDE_GAIN_CONTROL_H_
     13 
     14 #include "webrtc/typedefs.h"
     15 
     16 // Errors
     17 #define AGC_UNSPECIFIED_ERROR           18000
     18 #define AGC_UNSUPPORTED_FUNCTION_ERROR  18001
     19 #define AGC_UNINITIALIZED_ERROR         18002
     20 #define AGC_NULL_POINTER_ERROR          18003
     21 #define AGC_BAD_PARAMETER_ERROR         18004
     22 
     23 // Warnings
     24 #define AGC_BAD_PARAMETER_WARNING       18050
     25 
     26 enum
     27 {
     28     kAgcModeUnchanged,
     29     kAgcModeAdaptiveAnalog,
     30     kAgcModeAdaptiveDigital,
     31     kAgcModeFixedDigital
     32 };
     33 
     34 enum
     35 {
     36     kAgcFalse = 0,
     37     kAgcTrue
     38 };
     39 
     40 typedef struct
     41 {
     42     int16_t targetLevelDbfs;   // default 3 (-3 dBOv)
     43     int16_t compressionGaindB; // default 9 dB
     44     uint8_t limiterEnable;     // default kAgcTrue (on)
     45 } WebRtcAgc_config_t;
     46 
     47 #if defined(__cplusplus)
     48 extern "C"
     49 {
     50 #endif
     51 
     52 /*
     53  * This function processes a 10/20ms frame of far-end speech to determine
     54  * if there is active speech. Far-end speech length can be either 10ms or
     55  * 20ms. The length of the input speech vector must be given in samples
     56  * (80/160 when FS=8000, and 160/320 when FS=16000 or FS=32000).
     57  *
     58  * Input:
     59  *      - agcInst           : AGC instance.
     60  *      - inFar             : Far-end input speech vector (10 or 20ms)
     61  *      - samples           : Number of samples in input vector
     62  *
     63  * Return value:
     64  *                          :  0 - Normal operation.
     65  *                          : -1 - Error
     66  */
     67 int WebRtcAgc_AddFarend(void* agcInst,
     68                         const int16_t* inFar,
     69                         int16_t samples);
     70 
     71 /*
     72  * This function processes a 10/20ms frame of microphone speech to determine
     73  * if there is active speech. Microphone speech length can be either 10ms or
     74  * 20ms. The length of the input speech vector must be given in samples
     75  * (80/160 when FS=8000, and 160/320 when FS=16000 or FS=32000). For very low
     76  * input levels, the input signal is increased in level by multiplying and
     77  * overwriting the samples in inMic[].
     78  *
     79  * This function should be called before any further processing of the
     80  * near-end microphone signal.
     81  *
     82  * Input:
     83  *      - agcInst           : AGC instance.
     84  *      - inMic             : Microphone input speech vector (10 or 20 ms) for
     85  *                            L band
     86  *      - inMic_H           : Microphone input speech vector (10 or 20 ms) for
     87  *                            H band
     88  *      - samples           : Number of samples in input vector
     89  *
     90  * Return value:
     91  *                          :  0 - Normal operation.
     92  *                          : -1 - Error
     93  */
     94 int WebRtcAgc_AddMic(void* agcInst,
     95                      int16_t* inMic,
     96                      int16_t* inMic_H,
     97                      int16_t samples);
     98 
     99 /*
    100  * This function replaces the analog microphone with a virtual one.
    101  * It is a digital gain applied to the input signal and is used in the
    102  * agcAdaptiveDigital mode where no microphone level is adjustable.
    103  * Microphone speech length can be either 10ms or 20ms. The length of the
    104  * input speech vector must be given in samples (80/160 when FS=8000, and
    105  * 160/320 when FS=16000 or FS=32000).
    106  *
    107  * Input:
    108  *      - agcInst           : AGC instance.
    109  *      - inMic             : Microphone input speech vector for (10 or 20 ms)
    110  *                            L band
    111  *      - inMic_H           : Microphone input speech vector for (10 or 20 ms)
    112  *                            H band
    113  *      - samples           : Number of samples in input vector
    114  *      - micLevelIn        : Input level of microphone (static)
    115  *
    116  * Output:
    117  *      - inMic             : Microphone output after processing (L band)
    118  *      - inMic_H           : Microphone output after processing (H band)
    119  *      - micLevelOut       : Adjusted microphone level after processing
    120  *
    121  * Return value:
    122  *                          :  0 - Normal operation.
    123  *                          : -1 - Error
    124  */
    125 int WebRtcAgc_VirtualMic(void* agcInst,
    126                          int16_t* inMic,
    127                          int16_t* inMic_H,
    128                          int16_t samples,
    129                          int32_t micLevelIn,
    130                          int32_t* micLevelOut);
    131 
    132 /*
    133  * This function processes a 10/20ms frame and adjusts (normalizes) the gain
    134  * both analog and digitally. The gain adjustments are done only during
    135  * active periods of speech. The input speech length can be either 10ms or
    136  * 20ms and the output is of the same length. The length of the speech
    137  * vectors must be given in samples (80/160 when FS=8000, and 160/320 when
    138  * FS=16000 or FS=32000). The echo parameter can be used to ensure the AGC will
    139  * not adjust upward in the presence of echo.
    140  *
    141  * This function should be called after processing the near-end microphone
    142  * signal, in any case after any echo cancellation.
    143  *
    144  * Input:
    145  *      - agcInst           : AGC instance
    146  *      - inNear            : Near-end input speech vector (10 or 20 ms) for
    147  *                            L band
    148  *      - inNear_H          : Near-end input speech vector (10 or 20 ms) for
    149  *                            H band
    150  *      - samples           : Number of samples in input/output vector
    151  *      - inMicLevel        : Current microphone volume level
    152  *      - echo              : Set to 0 if the signal passed to add_mic is
    153  *                            almost certainly free of echo; otherwise set
    154  *                            to 1. If you have no information regarding echo
    155  *                            set to 0.
    156  *
    157  * Output:
    158  *      - outMicLevel       : Adjusted microphone volume level
    159  *      - out               : Gain-adjusted near-end speech vector (L band)
    160  *                          : May be the same vector as the input.
    161  *      - out_H             : Gain-adjusted near-end speech vector (H band)
    162  *      - saturationWarning : A returned value of 1 indicates a saturation event
    163  *                            has occurred and the volume cannot be further
    164  *                            reduced. Otherwise will be set to 0.
    165  *
    166  * Return value:
    167  *                          :  0 - Normal operation.
    168  *                          : -1 - Error
    169  */
    170 int WebRtcAgc_Process(void* agcInst,
    171                       const int16_t* inNear,
    172                       const int16_t* inNear_H,
    173                       int16_t samples,
    174                       int16_t* out,
    175                       int16_t* out_H,
    176                       int32_t inMicLevel,
    177                       int32_t* outMicLevel,
    178                       int16_t echo,
    179                       uint8_t* saturationWarning);
    180 
    181 /*
    182  * This function sets the config parameters (targetLevelDbfs,
    183  * compressionGaindB and limiterEnable).
    184  *
    185  * Input:
    186  *      - agcInst           : AGC instance
    187  *      - config            : config struct
    188  *
    189  * Output:
    190  *
    191  * Return value:
    192  *                          :  0 - Normal operation.
    193  *                          : -1 - Error
    194  */
    195 int WebRtcAgc_set_config(void* agcInst, WebRtcAgc_config_t config);
    196 
    197 /*
    198  * This function returns the config parameters (targetLevelDbfs,
    199  * compressionGaindB and limiterEnable).
    200  *
    201  * Input:
    202  *      - agcInst           : AGC instance
    203  *
    204  * Output:
    205  *      - config            : config struct
    206  *
    207  * Return value:
    208  *                          :  0 - Normal operation.
    209  *                          : -1 - Error
    210  */
    211 int WebRtcAgc_get_config(void* agcInst, WebRtcAgc_config_t* config);
    212 
    213 /*
    214  * This function creates an AGC instance, which will contain the state
    215  * information for one (duplex) channel.
    216  *
    217  * Return value             : AGC instance if successful
    218  *                          : 0 (i.e., a NULL pointer) if unsuccessful
    219  */
    220 int WebRtcAgc_Create(void **agcInst);
    221 
    222 /*
    223  * This function frees the AGC instance created at the beginning.
    224  *
    225  * Input:
    226  *      - agcInst           : AGC instance.
    227  *
    228  * Return value             :  0 - Ok
    229  *                            -1 - Error
    230  */
    231 int WebRtcAgc_Free(void *agcInst);
    232 
    233 /*
    234  * This function initializes an AGC instance.
    235  *
    236  * Input:
    237  *      - agcInst           : AGC instance.
    238  *      - minLevel          : Minimum possible mic level
    239  *      - maxLevel          : Maximum possible mic level
    240  *      - agcMode           : 0 - Unchanged
    241  *                          : 1 - Adaptive Analog Automatic Gain Control -3dBOv
    242  *                          : 2 - Adaptive Digital Automatic Gain Control -3dBOv
    243  *                          : 3 - Fixed Digital Gain 0dB
    244  *      - fs                : Sampling frequency
    245  *
    246  * Return value             :  0 - Ok
    247  *                            -1 - Error
    248  */
    249 int WebRtcAgc_Init(void *agcInst,
    250                    int32_t minLevel,
    251                    int32_t maxLevel,
    252                    int16_t agcMode,
    253                    uint32_t fs);
    254 
    255 #if defined(__cplusplus)
    256 }
    257 #endif
    258 
    259 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AGC_INCLUDE_GAIN_CONTROL_H_
    260