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