249 lines
11 KiB
C
249 lines
11 KiB
C
|
/*
|
||
|
|
* 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_
|