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 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 "typedefs.h"
18
19// Releases the memory allocated by WebRtc_CreateDelayEstimator(...)
20// Input:
21//      - handle        : Pointer to the delay estimation instance.
22//
23int WebRtc_FreeDelayEstimator(void* handle);
24
25// Allocates the memory needed by the delay estimation. The memory needs to be
26// initialized separately through WebRtc_InitDelayEstimator(...).
27//
28// Inputs:
29//      - handle        : Instance that should be created.
30//      - spectrum_size : Size of the spectrum used both in far-end and
31//                        near-end. Used to allocate memory for spectrum
32//                        specific buffers.
33//      - max_delay     : The maximum delay which can be estimated. Needed to
34//                        allocate memory for history buffers.
35//      - lookahead     : Amount of non-causal lookahead to use. This can
36//                        detect cases in which a near-end signal occurs before
37//                        the corresponding far-end signal. It will delay the
38//                        estimate for the current block by an equal amount,
39//                        and the returned values will be offset by it.
40//
41//                        A value of zero is the typical no-lookahead case.
42//                        This also represents the minimum delay which can be
43//                        estimated.
44//
45// Output:
46//      - handle        : Created instance.
47//
48int WebRtc_CreateDelayEstimator(void** handle,
49                                int spectrum_size,
50                                int max_delay,
51                                int lookahead);
52
53// Initializes the delay estimation instance created with
54// WebRtc_CreateDelayEstimator(...)
55// Input:
56//      - handle        : Pointer to the delay estimation instance.
57//
58// Output:
59//      - handle        : Initialized instance.
60//
61int WebRtc_InitDelayEstimator(void* handle);
62
63// Estimates and returns the delay between the far-end and near-end blocks. The
64// value will be offset by the lookahead (i.e. the lookahead should be
65// subtracted from the returned value).
66// Inputs:
67//      - handle        : Pointer to the delay estimation instance.
68//      - far_spectrum  : Pointer to the far-end spectrum data.
69//      - near_spectrum : Pointer to the near-end spectrum data of the current
70//                        block.
71//      - spectrum_size : The size of the data arrays (same for both far- and
72//                        near-end).
73//      - far_q         : The Q-domain of the far-end data.
74//      - near_q        : The Q-domain of the near-end data.
75//
76// Output:
77//      - handle        : Updated instance.
78//
79// Return value:
80//      - delay         :  >= 0 - Calculated delay value.
81//                        -1    - Error.
82//                        -2    - Insufficient data for estimation.
83//
84int WebRtc_DelayEstimatorProcessFix(void* handle,
85                                    uint16_t* far_spectrum,
86                                    uint16_t* near_spectrum,
87                                    int spectrum_size,
88                                    int far_q,
89                                    int near_q);
90
91// See WebRtc_DelayEstimatorProcessFix() for description.
92int WebRtc_DelayEstimatorProcessFloat(void* handle,
93                                      float* far_spectrum,
94                                      float* near_spectrum,
95                                      int spectrum_size);
96
97// Returns the last calculated delay updated by the function
98// WebRtc_DelayEstimatorProcess(...).
99//
100// Input:
101//      - handle        : Pointer to the delay estimation instance.
102//
103// Return value:
104//      - delay         :  >= 0 - Last calculated delay value.
105//                        -1    - Error.
106//                        -2    - Insufficient data for estimation.
107//
108int WebRtc_last_delay(void* handle);
109
110#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_WRAPPER_H_
111