/* * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. * * Use of this source code is governed by a BSD-style license * that can be found in the LICENSE file in the root of the source * tree. An additional intellectual property rights grant can be found * in the file PATENTS. All contributing project authors may * be found in the AUTHORS file in the root of the source tree. */ // Performs delay estimation on block by block basis. // The return value is 0 - OK and -1 - Error, unless otherwise stated. #ifndef MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_ #define MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_ #include <stdint.h> namespace webrtc { // Releases the memory allocated by WebRtc_CreateDelayEstimatorFarend(...) void WebRtc_FreeDelayEstimatorFarend(void* handle); // Allocates the memory needed by the far-end part of the delay estimation. The // memory needs to be initialized separately through // WebRtc_InitDelayEstimatorFarend(...). // // Inputs: // - spectrum_size : Size of the spectrum used both in far-end and // near-end. Used to allocate memory for spectrum // specific buffers. // - history_size : The far-end history buffer size. A change in buffer // size can be forced with WebRtc_set_history_size(). // Note that the maximum delay which can be estimated is // determined together with WebRtc_set_lookahead(). // // Return value: // - void* : Created `handle`. If the memory can't be allocated or // if any of the input parameters are invalid NULL is // returned. void* WebRtc_CreateDelayEstimatorFarend(int spectrum_size, int history_size); // Initializes the far-end part of the delay estimation instance returned by // WebRtc_CreateDelayEstimatorFarend(...) int WebRtc_InitDelayEstimatorFarend(void* handle); // Soft resets the far-end part of the delay estimation instance returned by // WebRtc_CreateDelayEstimatorFarend(...). // Input: // - delay_shift : The amount of blocks to shift history buffers. void WebRtc_SoftResetDelayEstimatorFarend(void* handle, int delay_shift); // Adds the far-end spectrum to the far-end history buffer. This spectrum is // used as reference when calculating the delay using // WebRtc_ProcessSpectrum(). // // Inputs: // - far_spectrum : Far-end spectrum. // - spectrum_size : The size of the data arrays (same for both far- and // near-end). // - far_q : The Q-domain of the far-end data. // // Output: // - handle : Updated far-end instance. // int WebRtc_AddFarSpectrumFix(void* handle, const uint16_t* far_spectrum, int spectrum_size, int far_q); // See WebRtc_AddFarSpectrumFix() for description. int WebRtc_AddFarSpectrumFloat(void* handle, const float* far_spectrum, int spectrum_size); // Releases the memory allocated by WebRtc_CreateDelayEstimator(...) void WebRtc_FreeDelayEstimator(void* handle); // Allocates the memory needed by the delay estimation. The memory needs to be // initialized separately through WebRtc_InitDelayEstimator(...). // // Inputs: // - farend_handle : Pointer to the far-end part of the delay estimation // instance created prior to this call using // WebRtc_CreateDelayEstimatorFarend(). // // Note that WebRtc_CreateDelayEstimator does not take // ownership of `farend_handle`, which has to be torn // down properly after this instance. // // - max_lookahead : Maximum amount of non-causal lookahead allowed. The // actual amount of lookahead used can be controlled by // WebRtc_set_lookahead(...). The default `lookahead` is // set to `max_lookahead` at create time. Use // WebRtc_set_lookahead(...) before start if a different // value is desired. // // Using lookahead can detect cases in which a near-end // signal occurs before the corresponding far-end signal. // It will delay the estimate for the current block by an // equal amount, and the returned values will be offset // by it. // // A value of zero is the typical no-lookahead case. // This also represents the minimum delay which can be // estimated. // // Note that the effective range of delay estimates is // [-`lookahead`,... ,`history_size`-`lookahead`) // where `history_size` is set through // WebRtc_set_history_size(). // // Return value: // - void* : Created `handle`. If the memory can't be allocated or // if any of the input parameters are invalid NULL is // returned. void* WebRtc_CreateDelayEstimator(void* farend_handle, int max_lookahead); // Initializes the delay estimation instance returned by // WebRtc_CreateDelayEstimator(...) int WebRtc_InitDelayEstimator(void* handle); // Soft resets the delay estimation instance returned by // WebRtc_CreateDelayEstimator(...) // Input: // - delay_shift : The amount of blocks to shift history buffers. // // Return value: // - actual_shifts : The actual number of shifts performed. int WebRtc_SoftResetDelayEstimator(void* handle, int delay_shift); // Sets the effective `history_size` used. Valid values from 2. We simply need // at least two delays to compare to perform an estimate. If `history_size` is // changed, buffers are reallocated filling in with zeros if necessary. // Note that changing the `history_size` affects both buffers in far-end and // near-end. Hence it is important to change all DelayEstimators that use the // same reference far-end, to the same `history_size` value. // Inputs: // - handle : Pointer to the delay estimation instance. // - history_size : Effective history size to be used. // Return value: // - new_history_size : The new history size used. If the memory was not able // to be allocated 0 is returned. int WebRtc_set_history_size(void* handle, int history_size); // Returns the history_size currently used. // Input: // - handle : Pointer to the delay estimation instance. int WebRtc_history_size(const void* handle); // Sets the amount of `lookahead` to use. Valid values are [0, max_lookahead] // where `max_lookahead` was set at create time through // WebRtc_CreateDelayEstimator(...). // // Input: // - handle : Pointer to the delay estimation instance. // - lookahead : The amount of lookahead to be used. // // Return value: // - new_lookahead : The actual amount of lookahead set, unless `handle` is // a NULL pointer or `lookahead` is invalid, for which an // error is returned. int WebRtc_set_lookahead(void* handle, int lookahead); // Returns the amount of lookahead we currently use. // Input: // - handle : Pointer to the delay estimation instance. int WebRtc_lookahead(void* handle); // Sets the `allowed_offset` used in the robust validation scheme. If the // delay estimator is used in an echo control component, this parameter is // related to the filter length. In principle `allowed_offset` should be set to // the echo control filter length minus the expected echo duration, i.e., the // delay offset the echo control can handle without quality regression. The // default value, used if not set manually, is zero. Note that `allowed_offset` // has to be non-negative. // Inputs: // - handle : Pointer to the delay estimation instance. // - allowed_offset : The amount of delay offset, measured in partitions, // the echo control filter can handle. int WebRtc_set_allowed_offset(void* handle, int allowed_offset); // Returns the `allowed_offset` in number of partitions. int WebRtc_get_allowed_offset(const void* handle); // Enables/Disables a robust validation functionality in the delay estimation. // This is by default set to disabled at create time. The state is preserved // over a reset. // Inputs: // - handle : Pointer to the delay estimation instance. // - enable : Enable (1) or disable (0) this feature. int WebRtc_enable_robust_validation(void* handle, int enable); // Returns 1 if robust validation is enabled and 0 if disabled. int WebRtc_is_robust_validation_enabled(const void* handle); // Estimates and returns the delay between the far-end and near-end blocks. The // value will be offset by the lookahead (i.e. the lookahead should be // subtracted from the returned value). // Inputs: // - handle : Pointer to the delay estimation instance. // - near_spectrum : Pointer to the near-end spectrum data of the current // block. // - spectrum_size : The size of the data arrays (same for both far- and // near-end). // - near_q : The Q-domain of the near-end data. // // Output: // - handle : Updated instance. // // Return value: // - delay : >= 0 - Calculated delay value. // -1 - Error. // -2 - Insufficient data for estimation. int WebRtc_DelayEstimatorProcessFix(void* handle, const uint16_t* near_spectrum, int spectrum_size, int near_q); // See WebRtc_DelayEstimatorProcessFix() for description. int WebRtc_DelayEstimatorProcessFloat(void* handle, const float* near_spectrum, int spectrum_size); // Returns the last calculated delay updated by the function // WebRtc_DelayEstimatorProcess(...). // // Input: // - handle : Pointer to the delay estimation instance. // // Return value: // - delay : >= 0 - Last calculated delay value. // -1 - Error. // -2 - Insufficient data for estimation. int WebRtc_last_delay(void* handle); // Returns the estimation quality/probability of the last calculated delay // updated by the function WebRtc_DelayEstimatorProcess(...). The estimation // quality is a value in the interval [0, 1]. The higher the value, the better // the quality. // // Return value: // - delay_quality : >= 0 - Estimation quality of last calculated delay. float WebRtc_last_delay_quality(void* handle); } // namespace webrtc #endif // MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_