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