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