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 binary converted spectra. 12 // The return value is 0 - OK and -1 - Error, unless otherwise stated. 13 14 #ifndef WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_ 15 #define WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_ 16 17 #include "webrtc/typedefs.h" 18 19 static const int32_t kMaxBitCountsQ9 = (32 << 9); // 32 matching bits in Q9. 20 21 typedef struct { 22 // Pointer to bit counts. 23 int* far_bit_counts; 24 // Binary history variables. 25 uint32_t* binary_far_history; 26 int history_size; 27 } BinaryDelayEstimatorFarend; 28 29 typedef struct { 30 // Pointer to bit counts. 31 int32_t* mean_bit_counts; 32 // Array only used locally in ProcessBinarySpectrum() but whose size is 33 // determined at run-time. 34 int32_t* bit_counts; 35 36 // Binary history variables. 37 uint32_t* binary_near_history; 38 int near_history_size; 39 int history_size; 40 41 // Delay estimation variables. 42 int32_t minimum_probability; 43 int last_delay_probability; 44 45 // Delay memory. 46 int last_delay; 47 48 // Robust validation 49 int robust_validation_enabled; 50 int allowed_offset; 51 int last_candidate_delay; 52 int compare_delay; 53 int candidate_hits; 54 float* histogram; 55 float last_delay_histogram; 56 57 // For dynamically changing the lookahead when using SoftReset...(). 58 int lookahead; 59 60 // Far-end binary spectrum history buffer etc. 61 BinaryDelayEstimatorFarend* farend; 62 } BinaryDelayEstimator; 63 64 // Releases the memory allocated by 65 // WebRtc_CreateBinaryDelayEstimatorFarend(...). 66 // Input: 67 // - self : Pointer to the binary delay estimation far-end 68 // instance which is the return value of 69 // WebRtc_CreateBinaryDelayEstimatorFarend(). 70 // 71 void WebRtc_FreeBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self); 72 73 // Allocates the memory needed by the far-end part of the binary delay 74 // estimation. The memory needs to be initialized separately through 75 // WebRtc_InitBinaryDelayEstimatorFarend(...). 76 // 77 // Inputs: 78 // - history_size : Size of the far-end binary spectrum history. 79 // 80 // Return value: 81 // - BinaryDelayEstimatorFarend* 82 // : Created |handle|. If the memory can't be allocated 83 // or if any of the input parameters are invalid NULL 84 // is returned. 85 // 86 BinaryDelayEstimatorFarend* WebRtc_CreateBinaryDelayEstimatorFarend( 87 int history_size); 88 89 // Re-allocates the buffers. 90 // 91 // Inputs: 92 // - self : Pointer to the binary estimation far-end instance 93 // which is the return value of 94 // WebRtc_CreateBinaryDelayEstimatorFarend(). 95 // - history_size : Size of the far-end binary spectrum history. 96 // 97 // Return value: 98 // - history_size : The history size allocated. 99 int WebRtc_AllocateFarendBufferMemory(BinaryDelayEstimatorFarend* self, 100 int history_size); 101 102 // Initializes the delay estimation far-end instance created with 103 // WebRtc_CreateBinaryDelayEstimatorFarend(...). 104 // 105 // Input: 106 // - self : Pointer to the delay estimation far-end instance. 107 // 108 // Output: 109 // - self : Initialized far-end instance. 110 // 111 void WebRtc_InitBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self); 112 113 // Soft resets the delay estimation far-end instance created with 114 // WebRtc_CreateBinaryDelayEstimatorFarend(...). 115 // 116 // Input: 117 // - delay_shift : The amount of blocks to shift history buffers. 118 // 119 void WebRtc_SoftResetBinaryDelayEstimatorFarend( 120 BinaryDelayEstimatorFarend* self, int delay_shift); 121 122 // Adds the binary far-end spectrum to the internal far-end history buffer. This 123 // spectrum is used as reference when calculating the delay using 124 // WebRtc_ProcessBinarySpectrum(). 125 // 126 // Inputs: 127 // - self : Pointer to the delay estimation far-end 128 // instance. 129 // - binary_far_spectrum : Far-end binary spectrum. 130 // 131 // Output: 132 // - self : Updated far-end instance. 133 // 134 void WebRtc_AddBinaryFarSpectrum(BinaryDelayEstimatorFarend* self, 135 uint32_t binary_far_spectrum); 136 137 // Releases the memory allocated by WebRtc_CreateBinaryDelayEstimator(...). 138 // 139 // Note that BinaryDelayEstimator utilizes BinaryDelayEstimatorFarend, but does 140 // not take ownership of it, hence the BinaryDelayEstimator has to be torn down 141 // before the far-end. 142 // 143 // Input: 144 // - self : Pointer to the binary delay estimation instance 145 // which is the return value of 146 // WebRtc_CreateBinaryDelayEstimator(). 147 // 148 void WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* self); 149 150 // Allocates the memory needed by the binary delay estimation. The memory needs 151 // to be initialized separately through WebRtc_InitBinaryDelayEstimator(...). 152 // 153 // See WebRtc_CreateDelayEstimator(..) in delay_estimator_wrapper.c for detailed 154 // description. 155 BinaryDelayEstimator* WebRtc_CreateBinaryDelayEstimator( 156 BinaryDelayEstimatorFarend* farend, int max_lookahead); 157 158 // Re-allocates |history_size| dependent buffers. The far-end buffers will be 159 // updated at the same time if needed. 160 // 161 // Input: 162 // - self : Pointer to the binary estimation instance which is 163 // the return value of 164 // WebRtc_CreateBinaryDelayEstimator(). 165 // - history_size : Size of the history buffers. 166 // 167 // Return value: 168 // - history_size : The history size allocated. 169 int WebRtc_AllocateHistoryBufferMemory(BinaryDelayEstimator* self, 170 int history_size); 171 172 // Initializes the delay estimation instance created with 173 // WebRtc_CreateBinaryDelayEstimator(...). 174 // 175 // Input: 176 // - self : Pointer to the delay estimation instance. 177 // 178 // Output: 179 // - self : Initialized instance. 180 // 181 void WebRtc_InitBinaryDelayEstimator(BinaryDelayEstimator* self); 182 183 // Soft resets the delay estimation instance created with 184 // WebRtc_CreateBinaryDelayEstimator(...). 185 // 186 // Input: 187 // - delay_shift : The amount of blocks to shift history buffers. 188 // 189 // Return value: 190 // - actual_shifts : The actual number of shifts performed. 191 // 192 int WebRtc_SoftResetBinaryDelayEstimator(BinaryDelayEstimator* self, 193 int delay_shift); 194 195 // Estimates and returns the delay between the binary far-end and binary near- 196 // end spectra. It is assumed the binary far-end spectrum has been added using 197 // WebRtc_AddBinaryFarSpectrum() prior to this call. The value will be offset by 198 // the lookahead (i.e. the lookahead should be subtracted from the returned 199 // value). 200 // 201 // Inputs: 202 // - self : Pointer to the delay estimation instance. 203 // - binary_near_spectrum : Near-end binary spectrum of the current block. 204 // 205 // Output: 206 // - self : Updated instance. 207 // 208 // Return value: 209 // - delay : >= 0 - Calculated delay value. 210 // -2 - Insufficient data for estimation. 211 // 212 int WebRtc_ProcessBinarySpectrum(BinaryDelayEstimator* self, 213 uint32_t binary_near_spectrum); 214 215 // Returns the last calculated delay updated by the function 216 // WebRtc_ProcessBinarySpectrum(...). 217 // 218 // Input: 219 // - self : Pointer to the delay estimation instance. 220 // 221 // Return value: 222 // - delay : >= 0 - Last calculated delay value 223 // -2 - Insufficient data for estimation. 224 // 225 int WebRtc_binary_last_delay(BinaryDelayEstimator* self); 226 227 // Returns the estimation quality of the last calculated delay updated by the 228 // function WebRtc_ProcessBinarySpectrum(...). The estimation quality is a value 229 // in the interval [0, 1]. The higher the value, the better the quality. 230 // 231 // Return value: 232 // - delay_quality : >= 0 - Estimation quality of last calculated 233 // delay value. 234 float WebRtc_binary_last_delay_quality(BinaryDelayEstimator* self); 235 236 // Updates the |mean_value| recursively with a step size of 2^-|factor|. This 237 // function is used internally in the Binary Delay Estimator as well as the 238 // Fixed point wrapper. 239 // 240 // Inputs: 241 // - new_value : The new value the mean should be updated with. 242 // - factor : The step size, in number of right shifts. 243 // 244 // Input/Output: 245 // - mean_value : Pointer to the mean value. 246 // 247 void WebRtc_MeanEstimatorFix(int32_t new_value, 248 int factor, 249 int32_t* mean_value); 250 251 #endif // WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_ 252