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 19static const int32_t kMaxBitCountsQ9 = (32 << 9); // 32 matching bits in Q9. 20 21typedef 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 29typedef 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// 71void 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// 86BinaryDelayEstimatorFarend* 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. 99int 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// 111void 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// 119void 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// 134void 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// 148void 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. 155BinaryDelayEstimator* 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. 169int 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// 181void 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// 192int 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// 212int 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// 225int 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. 234float 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// 247void 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