Source code
Revision control
Copy as Markdown
Other Tools
/*
* 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_