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