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 // Performs delay estimation on block by block basis. 12 // The return value is 0 - OK and -1 - Error, unless otherwise stated. 13 14 #ifndef WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_ 15 #define WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_ 16 17 #include "webrtc/typedefs.h" 18 19 // Releases the memory allocated by WebRtc_CreateDelayEstimatorFarend(...) 20 void WebRtc_FreeDelayEstimatorFarend(void* handle); 21 22 // Allocates the memory needed by the far-end part of the delay estimation. The 23 // memory needs to be initialized separately through 24 // WebRtc_InitDelayEstimatorFarend(...). 25 // 26 // Inputs: 27 // - spectrum_size : Size of the spectrum used both in far-end and 28 // near-end. Used to allocate memory for spectrum 29 // specific buffers. 30 // - history_size : The far-end history buffer size. A change in buffer 31 // size can be forced with WebRtc_set_history_size(). 32 // Note that the maximum delay which can be estimated is 33 // determined together with WebRtc_set_lookahead(). 34 // 35 // Return value: 36 // - void* : Created |handle|. If the memory can't be allocated or 37 // if any of the input parameters are invalid NULL is 38 // returned. 39 void* WebRtc_CreateDelayEstimatorFarend(int spectrum_size, int history_size); 40 41 // Initializes the far-end part of the delay estimation instance returned by 42 // WebRtc_CreateDelayEstimatorFarend(...) 43 int WebRtc_InitDelayEstimatorFarend(void* handle); 44 45 // Soft resets the far-end part of the delay estimation instance returned by 46 // WebRtc_CreateDelayEstimatorFarend(...). 47 // Input: 48 // - delay_shift : The amount of blocks to shift history buffers. 49 void WebRtc_SoftResetDelayEstimatorFarend(void* handle, int delay_shift); 50 51 // Adds the far-end spectrum to the far-end history buffer. This spectrum is 52 // used as reference when calculating the delay using 53 // WebRtc_ProcessSpectrum(). 54 // 55 // Inputs: 56 // - far_spectrum : Far-end spectrum. 57 // - spectrum_size : The size of the data arrays (same for both far- and 58 // near-end). 59 // - far_q : The Q-domain of the far-end data. 60 // 61 // Output: 62 // - handle : Updated far-end instance. 63 // 64 int WebRtc_AddFarSpectrumFix(void* handle, 65 const uint16_t* far_spectrum, 66 int spectrum_size, 67 int far_q); 68 69 // See WebRtc_AddFarSpectrumFix() for description. 70 int WebRtc_AddFarSpectrumFloat(void* handle, 71 const float* far_spectrum, 72 int spectrum_size); 73 74 // Releases the memory allocated by WebRtc_CreateDelayEstimator(...) 75 void WebRtc_FreeDelayEstimator(void* handle); 76 77 // Allocates the memory needed by the delay estimation. The memory needs to be 78 // initialized separately through WebRtc_InitDelayEstimator(...). 79 // 80 // Inputs: 81 // - farend_handle : Pointer to the far-end part of the delay estimation 82 // instance created prior to this call using 83 // WebRtc_CreateDelayEstimatorFarend(). 84 // 85 // Note that WebRtc_CreateDelayEstimator does not take 86 // ownership of |farend_handle|, which has to be torn 87 // down properly after this instance. 88 // 89 // - max_lookahead : Maximum amount of non-causal lookahead allowed. The 90 // actual amount of lookahead used can be controlled by 91 // WebRtc_set_lookahead(...). The default |lookahead| is 92 // set to |max_lookahead| at create time. Use 93 // WebRtc_set_lookahead(...) before start if a different 94 // value is desired. 95 // 96 // Using lookahead can detect cases in which a near-end 97 // signal occurs before the corresponding far-end signal. 98 // It will delay the estimate for the current block by an 99 // equal amount, and the returned values will be offset 100 // by it. 101 // 102 // A value of zero is the typical no-lookahead case. 103 // This also represents the minimum delay which can be 104 // estimated. 105 // 106 // Note that the effective range of delay estimates is 107 // [-|lookahead|,... ,|history_size|-|lookahead|) 108 // where |history_size| is set through 109 // WebRtc_set_history_size(). 110 // 111 // Return value: 112 // - void* : Created |handle|. If the memory can't be allocated or 113 // if any of the input parameters are invalid NULL is 114 // returned. 115 void* WebRtc_CreateDelayEstimator(void* farend_handle, int max_lookahead); 116 117 // Initializes the delay estimation instance returned by 118 // WebRtc_CreateDelayEstimator(...) 119 int WebRtc_InitDelayEstimator(void* handle); 120 121 // Soft resets the delay estimation instance returned by 122 // WebRtc_CreateDelayEstimator(...) 123 // Input: 124 // - delay_shift : The amount of blocks to shift history buffers. 125 // 126 // Return value: 127 // - actual_shifts : The actual number of shifts performed. 128 int WebRtc_SoftResetDelayEstimator(void* handle, int delay_shift); 129 130 // Sets the effective |history_size| used. Valid values from 2. We simply need 131 // at least two delays to compare to perform an estimate. If |history_size| is 132 // changed, buffers are reallocated filling in with zeros if necessary. 133 // Note that changing the |history_size| affects both buffers in far-end and 134 // near-end. Hence it is important to change all DelayEstimators that use the 135 // same reference far-end, to the same |history_size| value. 136 // Inputs: 137 // - handle : Pointer to the delay estimation instance. 138 // - history_size : Effective history size to be used. 139 // Return value: 140 // - new_history_size : The new history size used. If the memory was not able 141 // to be allocated 0 is returned. 142 int WebRtc_set_history_size(void* handle, int history_size); 143 144 // Returns the history_size currently used. 145 // Input: 146 // - handle : Pointer to the delay estimation instance. 147 int WebRtc_history_size(const void* handle); 148 149 // Sets the amount of |lookahead| to use. Valid values are [0, max_lookahead] 150 // where |max_lookahead| was set at create time through 151 // WebRtc_CreateDelayEstimator(...). 152 // 153 // Input: 154 // - handle : Pointer to the delay estimation instance. 155 // - lookahead : The amount of lookahead to be used. 156 // 157 // Return value: 158 // - new_lookahead : The actual amount of lookahead set, unless |handle| is 159 // a NULL pointer or |lookahead| is invalid, for which an 160 // error is returned. 161 int WebRtc_set_lookahead(void* handle, int lookahead); 162 163 // Returns the amount of lookahead we currently use. 164 // Input: 165 // - handle : Pointer to the delay estimation instance. 166 int WebRtc_lookahead(void* handle); 167 168 // Sets the |allowed_offset| used in the robust validation scheme. If the 169 // delay estimator is used in an echo control component, this parameter is 170 // related to the filter length. In principle |allowed_offset| should be set to 171 // the echo control filter length minus the expected echo duration, i.e., the 172 // delay offset the echo control can handle without quality regression. The 173 // default value, used if not set manually, is zero. Note that |allowed_offset| 174 // has to be non-negative. 175 // Inputs: 176 // - handle : Pointer to the delay estimation instance. 177 // - allowed_offset : The amount of delay offset, measured in partitions, 178 // the echo control filter can handle. 179 int WebRtc_set_allowed_offset(void* handle, int allowed_offset); 180 181 // Returns the |allowed_offset| in number of partitions. 182 int WebRtc_get_allowed_offset(const void* handle); 183 184 // Enables/Disables a robust validation functionality in the delay estimation. 185 // This is by default set to disabled at create time. The state is preserved 186 // over a reset. 187 // Inputs: 188 // - handle : Pointer to the delay estimation instance. 189 // - enable : Enable (1) or disable (0) this feature. 190 int WebRtc_enable_robust_validation(void* handle, int enable); 191 192 // Returns 1 if robust validation is enabled and 0 if disabled. 193 int WebRtc_is_robust_validation_enabled(const void* handle); 194 195 // Estimates and returns the delay between the far-end and near-end blocks. The 196 // value will be offset by the lookahead (i.e. the lookahead should be 197 // subtracted from the returned value). 198 // Inputs: 199 // - handle : Pointer to the delay estimation instance. 200 // - near_spectrum : Pointer to the near-end spectrum data of the current 201 // block. 202 // - spectrum_size : The size of the data arrays (same for both far- and 203 // near-end). 204 // - near_q : The Q-domain of the near-end data. 205 // 206 // Output: 207 // - handle : Updated instance. 208 // 209 // Return value: 210 // - delay : >= 0 - Calculated delay value. 211 // -1 - Error. 212 // -2 - Insufficient data for estimation. 213 int WebRtc_DelayEstimatorProcessFix(void* handle, 214 const uint16_t* near_spectrum, 215 int spectrum_size, 216 int near_q); 217 218 // See WebRtc_DelayEstimatorProcessFix() for description. 219 int WebRtc_DelayEstimatorProcessFloat(void* handle, 220 const float* near_spectrum, 221 int spectrum_size); 222 223 // Returns the last calculated delay updated by the function 224 // WebRtc_DelayEstimatorProcess(...). 225 // 226 // Input: 227 // - handle : Pointer to the delay estimation instance. 228 // 229 // Return value: 230 // - delay : >= 0 - Last calculated delay value. 231 // -1 - Error. 232 // -2 - Insufficient data for estimation. 233 int WebRtc_last_delay(void* handle); 234 235 // Returns the estimation quality/probability of the last calculated delay 236 // updated by the function WebRtc_DelayEstimatorProcess(...). The estimation 237 // quality is a value in the interval [0, 1]. The higher the value, the better 238 // the quality. 239 // 240 // Return value: 241 // - delay_quality : >= 0 - Estimation quality of last calculated delay. 242 float WebRtc_last_delay_quality(void* handle); 243 244 #endif // WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_ 245
