Note: We no longer publish the latest version of our code here. We primarily use a kumc-bmi github organization. The heron ETL repository, in particular, is not public. Peers in the informatics community should see MultiSiteDev for details on requesting access.

source: webrtc/webrtc/modules/audio_processing/utility/delay_estimator.h @ 0:4bda6873e34c

pub_scrub_3792 tip
Last change on this file since 0:4bda6873e34c was 0:4bda6873e34c, checked in by Michael Prittie <mprittie@…>, 6 years ago

Scrubbed password for publication.

File size: 8.4 KB
Line 
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 binary converted spectra.
12// The return value is  0 - OK and -1 - Error, unless otherwise stated.
13
14#ifndef WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_
15#define WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_
16
17#include "webrtc/typedefs.h"
18
19typedef struct {
20  // Pointer to bit counts.
21  int* far_bit_counts;
22  // Binary history variables.
23  uint32_t* binary_far_history;
24  int history_size;
25} BinaryDelayEstimatorFarend;
26
27typedef struct {
28  // Pointer to bit counts.
29  int32_t* mean_bit_counts;
30  // Array only used locally in ProcessBinarySpectrum() but whose size is
31  // determined at run-time.
32  int32_t* bit_counts;
33
34  // Binary history variables.
35  uint32_t* binary_near_history;
36  int near_history_size;
37
38  // Delay estimation variables.
39  int32_t minimum_probability;
40  int last_delay_probability;
41
42  // Delay memory.
43  int last_delay;
44
45  // Robust validation
46  int robust_validation_enabled;
47
48  // Far-end binary spectrum history buffer etc.
49  BinaryDelayEstimatorFarend* farend;
50} BinaryDelayEstimator;
51
52// Releases the memory allocated by
53// WebRtc_CreateBinaryDelayEstimatorFarend(...).
54// Input:
55//    - self              : Pointer to the binary delay estimation far-end
56//                          instance which is the return value of
57//                          WebRtc_CreateBinaryDelayEstimatorFarend().
58//
59void WebRtc_FreeBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self);
60
61// Allocates the memory needed by the far-end part of the binary delay
62// estimation. The memory needs to be initialized separately through
63// WebRtc_InitBinaryDelayEstimatorFarend(...).
64//
65// Inputs:
66//      - history_size    : Size of the far-end binary spectrum history.
67//
68// Return value:
69//      - BinaryDelayEstimatorFarend*
70//                        : Created |handle|. If the memory can't be allocated
71//                          or if any of the input parameters are invalid NULL
72//                          is returned.
73//
74BinaryDelayEstimatorFarend* WebRtc_CreateBinaryDelayEstimatorFarend(
75    int history_size);
76
77// Initializes the delay estimation far-end instance created with
78// WebRtc_CreateBinaryDelayEstimatorFarend(...).
79//
80// Input:
81//    - self              : Pointer to the delay estimation far-end instance.
82//
83// Output:
84//    - self              : Initialized far-end instance.
85//
86void WebRtc_InitBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self);
87
88// Adds the binary far-end spectrum to the internal far-end history buffer. This
89// spectrum is used as reference when calculating the delay using
90// WebRtc_ProcessBinarySpectrum().
91//
92// Inputs:
93//    - self                  : Pointer to the delay estimation far-end
94//                              instance.
95//    - binary_far_spectrum   : Far-end binary spectrum.
96//
97// Output:
98//    - self                  : Updated far-end instance.
99//
100void WebRtc_AddBinaryFarSpectrum(BinaryDelayEstimatorFarend* self,
101                                 uint32_t binary_far_spectrum);
102
103// Releases the memory allocated by WebRtc_CreateBinaryDelayEstimator(...).
104//
105// Note that BinaryDelayEstimator utilizes BinaryDelayEstimatorFarend, but does
106// not take ownership of it, hence the BinaryDelayEstimator has to be torn down
107// before the far-end.
108//
109// Input:
110//    - self              : Pointer to the binary delay estimation instance
111//                          which is the return value of
112//                          WebRtc_CreateBinaryDelayEstimator().
113//
114void WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* self);
115
116// Allocates the memory needed by the binary delay estimation. The memory needs
117// to be initialized separately through WebRtc_InitBinaryDelayEstimator(...).
118//
119// Inputs:
120//      - farend        : Pointer to the far-end part of the Binary Delay
121//                        Estimator. This memory has to be created separately
122//                        prior to this call using
123//                        WebRtc_CreateBinaryDelayEstimatorFarend().
124//
125//                        Note that BinaryDelayEstimator does not take
126//                        ownership of |farend|.
127//
128//      - lookahead     : Amount of non-causal lookahead to use. This can
129//                        detect cases in which a near-end signal occurs before
130//                        the corresponding far-end signal. It will delay the
131//                        estimate for the current block by an equal amount,
132//                        and the returned values will be offset by it.
133//
134//                        A value of zero is the typical no-lookahead case.
135//                        This also represents the minimum delay which can be
136//                        estimated.
137//
138//                        Note that the effective range of delay estimates is
139//                        [-|lookahead|,... ,|history_size|-|lookahead|)
140//                        where |history_size| was set upon creating the far-end
141//                        history buffer size.
142//
143// Return value:
144//      - BinaryDelayEstimator*
145//                        : Created |handle|. If the memory can't be allocated
146//                          or if any of the input parameters are invalid NULL
147//                          is returned.
148//
149BinaryDelayEstimator* WebRtc_CreateBinaryDelayEstimator(
150    BinaryDelayEstimatorFarend* farend, int lookahead);
151
152// Initializes the delay estimation instance created with
153// WebRtc_CreateBinaryDelayEstimator(...).
154//
155// Input:
156//    - self              : Pointer to the delay estimation instance.
157//
158// Output:
159//    - self              : Initialized instance.
160//
161void WebRtc_InitBinaryDelayEstimator(BinaryDelayEstimator* self);
162
163// Estimates and returns the delay between the binary far-end and binary near-
164// end spectra. It is assumed the binary far-end spectrum has been added using
165// WebRtc_AddBinaryFarSpectrum() prior to this call. The value will be offset by
166// the lookahead (i.e. the lookahead should be subtracted from the returned
167// value).
168//
169// Inputs:
170//    - self                  : Pointer to the delay estimation instance.
171//    - binary_near_spectrum  : Near-end binary spectrum of the current block.
172//
173// Output:
174//    - self                  : Updated instance.
175//
176// Return value:
177//    - delay                 :  >= 0 - Calculated delay value.
178//                              -2    - Insufficient data for estimation.
179//
180int WebRtc_ProcessBinarySpectrum(BinaryDelayEstimator* self,
181                                 uint32_t binary_near_spectrum);
182
183// Returns the last calculated delay updated by the function
184// WebRtc_ProcessBinarySpectrum(...).
185//
186// Input:
187//    - self                  : Pointer to the delay estimation instance.
188//
189// Return value:
190//    - delay                 :  >= 0 - Last calculated delay value
191//                              -2    - Insufficient data for estimation.
192//
193int WebRtc_binary_last_delay(BinaryDelayEstimator* self);
194
195// Returns the estimation quality of the last calculated delay updated by the
196// function WebRtc_ProcessBinarySpectrum(...). The estimation quality is a value
197// in the interval [0, 1] in Q14. The higher the value, the better quality.
198//
199// Input:
200//    - self                  : Pointer to the delay estimation instance.
201//
202// Return value:
203//    - delay_quality         :  >= 0 - Estimation quality (in Q14) of last
204//                                      calculated delay value.
205//                              -2    - Insufficient data for estimation.
206//
207int WebRtc_binary_last_delay_quality(BinaryDelayEstimator* self);
208
209// Updates the |mean_value| recursively with a step size of 2^-|factor|. This
210// function is used internally in the Binary Delay Estimator as well as the
211// Fixed point wrapper.
212//
213// Inputs:
214//    - new_value             : The new value the mean should be updated with.
215//    - factor                : The step size, in number of right shifts.
216//
217// Input/Output:
218//    - mean_value            : Pointer to the mean value.
219//
220void WebRtc_MeanEstimatorFix(int32_t new_value,
221                             int factor,
222                             int32_t* mean_value);
223
224
225#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_
Note: See TracBrowser for help on using the repository browser.