1/*
2 *  Copyright (c) 2011 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 "typedefs.h"
18
19typedef struct {
20  // Pointer to bit counts.
21  int32_t* mean_bit_counts;
22  int* far_bit_counts;
23
24  // Array only used locally in ProcessBinarySpectrum() but whose size is
25  // determined at run-time.
26  int32_t* bit_counts;
27
28  // Binary history variables.
29  uint32_t* binary_far_history;
30  uint32_t* binary_near_history;
31
32  // Delay estimation variables.
33  int32_t minimum_probability;
34  int last_delay_probability;
35
36  // Delay memory.
37  int last_delay;
38
39  // Buffer size.
40  int history_size;
41
42  // Near-end buffer size.
43  int near_history_size;
44} BinaryDelayEstimator;
45
46// Releases the memory allocated by WebRtc_CreateBinaryDelayEstimator(...).
47// Input:
48//    - handle            : Pointer to the delay estimation instance.
49//
50int WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* handle);
51
52// Refer to WebRtc_CreateDelayEstimator() in delay_estimator_wrapper.h.
53int WebRtc_CreateBinaryDelayEstimator(BinaryDelayEstimator** handle,
54                                      int max_delay,
55                                      int lookahead);
56
57// Initializes the delay estimation instance created with
58// WebRtc_CreateBinaryDelayEstimator(...).
59// Input:
60//    - handle            : Pointer to the delay estimation instance.
61//
62// Output:
63//    - handle            : Initialized instance.
64//
65int WebRtc_InitBinaryDelayEstimator(BinaryDelayEstimator* handle);
66
67// Estimates and returns the delay between the binary far-end and binary near-
68// end spectra. The value will be offset by the lookahead (i.e. the lookahead
69// should be subtracted from the returned value).
70// Inputs:
71//    - handle                : Pointer to the delay estimation instance.
72//    - binary_far_spectrum   : Far-end binary spectrum.
73//    - binary_near_spectrum  : Near-end binary spectrum of the current block.
74//
75// Output:
76//    - handle                : Updated instance.
77//
78// Return value:
79//    - delay                 :  >= 0 - Calculated delay value.
80//                              -1    - Error.
81//                              -2    - Insufficient data for estimation.
82//
83int WebRtc_ProcessBinarySpectrum(BinaryDelayEstimator* handle,
84                                 uint32_t binary_far_spectrum,
85                                 uint32_t binary_near_spectrum);
86
87// Returns the last calculated delay updated by the function
88// WebRtc_ProcessBinarySpectrum(...).
89//
90// Input:
91//    - handle                : Pointer to the delay estimation instance.
92//
93// Return value:
94//    - delay                 :  >= 0 - Last calculated delay value
95//                              -1    - Error
96//                              -2    - Insufficient data for estimation.
97//
98int WebRtc_binary_last_delay(BinaryDelayEstimator* handle);
99
100// Returns the history size used in the far-end buffers to calculate the delay
101// over.
102//
103// Input:
104//    - handle                : Pointer to the delay estimation instance.
105//
106// Return value:
107//    - history_size          :  > 0  - Far-end history size.
108//                              -1    - Error.
109//
110int WebRtc_history_size(BinaryDelayEstimator* handle);
111
112// Updates the |mean_value| recursively with a step size of 2^-|factor|. This
113// function is used internally in the Binary Delay Estimator as well as the
114// Fixed point wrapper.
115//
116// Inputs:
117//    - new_value             : The new value the mean should be updated with.
118//    - factor                : The step size, in number of right shifts.
119//
120// Input/Output:
121//    - mean_value            : Pointer to the mean value.
122//
123void WebRtc_MeanEstimatorFix(int32_t new_value,
124                             int factor,
125                             int32_t* mean_value);
126
127
128#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_
129