Home | History | Annotate | Download | only in utility 
      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 
     19 typedef 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 //
     50 int WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* handle);
     51 
     52 // Refer to WebRtc_CreateDelayEstimator() in delay_estimator_wrapper.h.
     53 int 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 //
     65 int 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 //
     83 int 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 //
     98 int 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 //
    110 int 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 //
    123 void 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