delay_estimator.cc | Explore in Territory

/*
 *  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.
 */

#include "modules/audio_processing/utility/delay_estimator.h"

#include <stdlib.h>
#include <string.h>

#include <algorithm>

#include "rtc_base/checks.h"

namespace webrtc {

namespace {

// Number of right shifts for scaling is linearly depending on number of bits in
// the far-end binary spectrum.
static const int kShiftsAtZero = …;  // Right shifts at zero binary spectrum.
static const int kShiftsLinearSlope = …;

static const int32_t kProbabilityOffset = …;      // 2 in Q9.
static const int32_t kProbabilityLowerLimit = …;  // 17 in Q9.
static const int32_t kProbabilityMinSpread = …;   // 5.5 in Q9.

// Robust validation settings
static const float kHistogramMax = …;
static const float kLastHistogramMax = …;
static const float kMinHistogramThreshold = …;
static const int kMinRequiredHits = …;
static const int kMaxHitsWhenPossiblyNonCausal = …;
static const int kMaxHitsWhenPossiblyCausal = …;
static const float kQ14Scaling = …;  // Scaling by 2^14 to get Q0.
static const float kFractionSlope = …;
static const float kMinFractionWhenPossiblyCausal = …;
static const float kMinFractionWhenPossiblyNonCausal = …;

}  // namespace

// Counts and returns number of bits of a 32-bit word.
static int BitCount(uint32_t u32) { … }

// Compares the `binary_vector` with all rows of the `binary_matrix` and counts
// per row the number of times they have the same value.
//
// Inputs:
//      - binary_vector     : binary "vector" stored in a long
//      - binary_matrix     : binary "matrix" stored as a vector of long
//      - matrix_size       : size of binary "matrix"
//
// Output:
//      - bit_counts        : "Vector" stored as a long, containing for each
//                            row the number of times the matrix row and the
//                            input vector have the same value
//
static void BitCountComparison(uint32_t binary_vector,
                               const uint32_t* binary_matrix,
                               int matrix_size,
                               int32_t* bit_counts) { … }

// Collects necessary statistics for the HistogramBasedValidation().  This
// function has to be called prior to calling HistogramBasedValidation().  The
// statistics updated and used by the HistogramBasedValidation() are:
//  1. the number of `candidate_hits`, which states for how long we have had the
//     same `candidate_delay`
//  2. the `histogram` of candidate delays over time.  This histogram is
//     weighted with respect to a reliability measure and time-varying to cope
//     with possible delay shifts.
// For further description see commented code.
//
// Inputs:
//  - candidate_delay   : The delay to validate.
//  - valley_depth_q14  : The cost function has a valley/minimum at the
//                        `candidate_delay` location.  `valley_depth_q14` is the
//                        cost function difference between the minimum and
//                        maximum locations.  The value is in the Q14 domain.
//  - valley_level_q14  : Is the cost function value at the minimum, in Q14.
static void UpdateRobustValidationStatistics(BinaryDelayEstimator* self,
                                             int candidate_delay,
                                             int32_t valley_depth_q14,
                                             int32_t valley_level_q14) { … }

// Validates the `candidate_delay`, estimated in WebRtc_ProcessBinarySpectrum(),
// based on a mix of counting concurring hits with a modified histogram
// of recent delay estimates.  In brief a candidate is valid (returns 1) if it
// is the most likely according to the histogram.  There are a couple of
// exceptions that are worth mentioning:
//  1. If the `candidate_delay` < `last_delay` it can be that we are in a
//     non-causal state, breaking a possible echo control algorithm.  Hence, we
//     open up for a quicker change by allowing the change even if the
//     `candidate_delay` is not the most likely one according to the histogram.
//  2. There's a minimum number of hits (kMinRequiredHits) and the histogram
//     value has to reached a minimum (kMinHistogramThreshold) to be valid.
//  3. The action is also depending on the filter length used for echo control.
//     If the delay difference is larger than what the filter can capture, we
//     also move quicker towards a change.
// For further description see commented code.
//
// Input:
//  - candidate_delay     : The delay to validate.
//
// Return value:
//  - is_histogram_valid  : 1 - The `candidate_delay` is valid.
//                          0 - Otherwise.
static int HistogramBasedValidation(const BinaryDelayEstimator* self,
                                    int candidate_delay) { … }

// Performs a robust validation of the `candidate_delay` estimated in
// WebRtc_ProcessBinarySpectrum().  The algorithm takes the
// `is_instantaneous_valid` and the `is_histogram_valid` and combines them
// into a robust validation.  The HistogramBasedValidation() has to be called
// prior to this call.
// For further description on how the combination is done, see commented code.
//
// Inputs:
//  - candidate_delay         : The delay to validate.
//  - is_instantaneous_valid  : The instantaneous validation performed in
//                              WebRtc_ProcessBinarySpectrum().
//  - is_histogram_valid      : The histogram based validation.
//
// Return value:
//  - is_robust               : 1 - The candidate_delay is valid according to a
//                                  combination of the two inputs.
//                            : 0 - Otherwise.
static int RobustValidation(const BinaryDelayEstimator* self,
                            int candidate_delay,
                            int is_instantaneous_valid,
                            int is_histogram_valid) { … }

void WebRtc_FreeBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self) { … }

BinaryDelayEstimatorFarend* WebRtc_CreateBinaryDelayEstimatorFarend(
    int history_size) { … }

int WebRtc_AllocateFarendBufferMemory(BinaryDelayEstimatorFarend* self,
                                      int history_size) { … }

void WebRtc_InitBinaryDelayEstimatorFarend(BinaryDelayEstimatorFarend* self) { … }

void WebRtc_SoftResetBinaryDelayEstimatorFarend(
    BinaryDelayEstimatorFarend* self,
    int delay_shift) { … }

void WebRtc_AddBinaryFarSpectrum(BinaryDelayEstimatorFarend* handle,
                                 uint32_t binary_far_spectrum) { … }

void WebRtc_FreeBinaryDelayEstimator(BinaryDelayEstimator* self) { … }

BinaryDelayEstimator* WebRtc_CreateBinaryDelayEstimator(
    BinaryDelayEstimatorFarend* farend,
    int max_lookahead) { … }

int WebRtc_AllocateHistoryBufferMemory(BinaryDelayEstimator* self,
                                       int history_size) { … }

void WebRtc_InitBinaryDelayEstimator(BinaryDelayEstimator* self) { … }

int WebRtc_SoftResetBinaryDelayEstimator(BinaryDelayEstimator* self,
                                         int delay_shift) { … }

int WebRtc_ProcessBinarySpectrum(BinaryDelayEstimator* self,
                                 uint32_t binary_near_spectrum) { … }

int WebRtc_binary_last_delay(BinaryDelayEstimator* self) { … }

float WebRtc_binary_last_delay_quality(BinaryDelayEstimator* self) { … }

void WebRtc_MeanEstimatorFix(int32_t new_value,
                             int factor,
                             int32_t* mean_value) { … }

}  // namespace webrtc
chromium/third_party/webrtc/modules/audio_processing/utility/delay_estimator.cc
