/* * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. * * Use of this source code is governed by a BSD-style license * that can be found in the LICENSE file in the root of the source * tree. An additional intellectual property rights grant can be found * in the file PATENTS. All contributing project authors may * be found in the AUTHORS file in the root of the source tree. */ // Performs delay estimation on binary converted spectra. // The return value is 0 - OK and -1 - Error, unless otherwise stated. #ifndef MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_ #define MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_ #include <stdint.h> namespace webrtc { static const int32_t kMaxBitCountsQ9 = …; // 32 matching bits in Q9. BinaryDelayEstimatorFarend; BinaryDelayEstimator; // Releases the memory allocated by // WebRtc_CreateBinaryDelayEstimatorFarend(...). // Input: // - self : Pointer to the binary delay estimation far-end // instance which is the return value of // WebRtc_CreateBinaryDelayEstimatorFarend(). // void WebRtc_FreeBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self); // Allocates the memory needed by the far-end part of the binary delay // estimation. The memory needs to be initialized separately through // WebRtc_InitBinaryDelayEstimatorFarend(...). // // Inputs: // - history_size : Size of the far-end binary spectrum history. // // Return value: // - BinaryDelayEstimatorFarend* // : Created `handle`. If the memory can't be allocated // or if any of the input parameters are invalid NULL // is returned. // BinaryDelayEstimatorFarend* WebRtc_CreateBinaryDelayEstimatorFarend( int history_size); // Re-allocates the buffers. // // Inputs: // - self : Pointer to the binary estimation far-end instance // which is the return value of // WebRtc_CreateBinaryDelayEstimatorFarend(). // - history_size : Size of the far-end binary spectrum history. // // Return value: // - history_size : The history size allocated. int WebRtc_AllocateFarendBufferMemory(BinaryDelayEstimatorFarend* self, int history_size); // Initializes the delay estimation far-end instance created with // WebRtc_CreateBinaryDelayEstimatorFarend(...). // // Input: // - self : Pointer to the delay estimation far-end instance. // // Output: // - self : Initialized far-end instance. // void WebRtc_InitBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self); // Soft resets the delay estimation far-end instance created with // WebRtc_CreateBinaryDelayEstimatorFarend(...). // // Input: // - delay_shift : The amount of blocks to shift history buffers. // void WebRtc_SoftResetBinaryDelayEstimatorFarend( BinaryDelayEstimatorFarend* self, int delay_shift); // Adds the binary far-end spectrum to the internal far-end history buffer. This // spectrum is used as reference when calculating the delay using // WebRtc_ProcessBinarySpectrum(). // // Inputs: // - self : Pointer to the delay estimation far-end // instance. // - binary_far_spectrum : Far-end binary spectrum. // // Output: // - self : Updated far-end instance. // void WebRtc_AddBinaryFarSpectrum(BinaryDelayEstimatorFarend* self, uint32_t binary_far_spectrum); // Releases the memory allocated by WebRtc_CreateBinaryDelayEstimator(...). // // Note that BinaryDelayEstimator utilizes BinaryDelayEstimatorFarend, but does // not take ownership of it, hence the BinaryDelayEstimator has to be torn down // before the far-end. // // Input: // - self : Pointer to the binary delay estimation instance // which is the return value of // WebRtc_CreateBinaryDelayEstimator(). // void WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* self); // Allocates the memory needed by the binary delay estimation. The memory needs // to be initialized separately through WebRtc_InitBinaryDelayEstimator(...). // // See WebRtc_CreateDelayEstimator(..) in delay_estimator_wrapper.c for detailed // description. BinaryDelayEstimator* WebRtc_CreateBinaryDelayEstimator( BinaryDelayEstimatorFarend* farend, int max_lookahead); // Re-allocates `history_size` dependent buffers. The far-end buffers will be // updated at the same time if needed. // // Input: // - self : Pointer to the binary estimation instance which is // the return value of // WebRtc_CreateBinaryDelayEstimator(). // - history_size : Size of the history buffers. // // Return value: // - history_size : The history size allocated. int WebRtc_AllocateHistoryBufferMemory(BinaryDelayEstimator* self, int history_size); // Initializes the delay estimation instance created with // WebRtc_CreateBinaryDelayEstimator(...). // // Input: // - self : Pointer to the delay estimation instance. // // Output: // - self : Initialized instance. // void WebRtc_InitBinaryDelayEstimator(BinaryDelayEstimator* self); // Soft resets the delay estimation instance created with // WebRtc_CreateBinaryDelayEstimator(...). // // Input: // - delay_shift : The amount of blocks to shift history buffers. // // Return value: // - actual_shifts : The actual number of shifts performed. // int WebRtc_SoftResetBinaryDelayEstimator(BinaryDelayEstimator* self, int delay_shift); // Estimates and returns the delay between the binary far-end and binary near- // end spectra. It is assumed the binary far-end spectrum has been added using // WebRtc_AddBinaryFarSpectrum() prior to this call. The value will be offset by // the lookahead (i.e. the lookahead should be subtracted from the returned // value). // // Inputs: // - self : Pointer to the delay estimation instance. // - binary_near_spectrum : Near-end binary spectrum of the current block. // // Output: // - self : Updated instance. // // Return value: // - delay : >= 0 - Calculated delay value. // -2 - Insufficient data for estimation. // int WebRtc_ProcessBinarySpectrum(BinaryDelayEstimator* self, uint32_t binary_near_spectrum); // Returns the last calculated delay updated by the function // WebRtc_ProcessBinarySpectrum(...). // // Input: // - self : Pointer to the delay estimation instance. // // Return value: // - delay : >= 0 - Last calculated delay value // -2 - Insufficient data for estimation. // int WebRtc_binary_last_delay(BinaryDelayEstimator* self); // Returns the estimation quality of the last calculated delay updated by the // function WebRtc_ProcessBinarySpectrum(...). The estimation quality is a value // in the interval [0, 1]. The higher the value, the better the quality. // // Return value: // - delay_quality : >= 0 - Estimation quality of last calculated // delay value. float WebRtc_binary_last_delay_quality(BinaryDelayEstimator* self); // Updates the `mean_value` recursively with a step size of 2^-`factor`. This // function is used internally in the Binary Delay Estimator as well as the // Fixed point wrapper. // // Inputs: // - new_value : The new value the mean should be updated with. // - factor : The step size, in number of right shifts. // // Input/Output: // - mean_value : Pointer to the mean value. // void WebRtc_MeanEstimatorFix(int32_t new_value, int factor, int32_t* mean_value); } // namespace webrtc #endif // MODULES_AUDIO_PROCESSING_UTILITY_DELAY_ESTIMATOR_H_