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