AEC3: Add metrics for API call jitter

Bug: webrtc:10021,chromium:907234
Change-Id: Ic0e6ba01c8dfdd5ca8230c8579bf149693e5f151
Reviewed-on: https://webrtc-review.googlesource.com/c/111580
Commit-Queue: Per Åhgren <peah@webrtc.org>
Reviewed-by: Gustaf Ullberg <gustaf@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#25806}

modules/audio_processing/aec3/BUILD.gn

@@ -20,6 +20,8 @@ rtc_static_library("aec3") {
     "aec3_fft.h",
     "aec_state.cc",
     "aec_state.h",
+    "api_call_jitter_metrics.cc",
+    "api_call_jitter_metrics.h",
     "block_delay_buffer.cc",
     "block_delay_buffer.h",
     "block_framer.cc",
@@ -192,6 +194,7 @@ if (rtc_include_tests) {
         "adaptive_fir_filter_unittest.cc",
         "aec3_fft_unittest.cc",
         "aec_state_unittest.cc",
+        "api_call_jitter_metrics_unittest.cc",
         "block_delay_buffer_unittest.cc",
         "block_framer_unittest.cc",
         "block_processor_metrics_unittest.cc",

modules/audio_processing/aec3/api_call_jitter_metrics.cc

@@ -0,0 +1,121 @@
+/*
+ *  Copyright (c) 2018 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/aec3/api_call_jitter_metrics.h"
+
+#include <algorithm>
+#include <limits>
+
+#include "modules/audio_processing/aec3/aec3_common.h"
+#include "system_wrappers/include/metrics.h"
+
+namespace webrtc {
+namespace {
+
+bool TimeToReportMetrics(int frames_since_last_report) {
+  constexpr int kNumFramesPerSecond = 100;
+  constexpr int kReportingIntervalFrames = 10 * kNumFramesPerSecond;
+  return frames_since_last_report == kReportingIntervalFrames;
+}
+
+}  // namespace
+
+ApiCallJitterMetrics::Jitter::Jitter()
+    : max_(0), min_(std::numeric_limits<int>::max()) {}
+
+void ApiCallJitterMetrics::Jitter::Update(int num_api_calls_in_a_row) {
+  min_ = std::min(min_, num_api_calls_in_a_row);
+  max_ = std::max(max_, num_api_calls_in_a_row);
+}
+
+void ApiCallJitterMetrics::Jitter::Reset() {
+  min_ = std::numeric_limits<int>::max();
+  max_ = 0;
+}
+
+void ApiCallJitterMetrics::Reset() {
+  render_jitter_.Reset();
+  capture_jitter_.Reset();
+  num_api_calls_in_a_row_ = 0;
+  frames_since_last_report_ = 0;
+  last_call_was_render_ = false;
+  proper_call_observed_ = false;
+}
+
+void ApiCallJitterMetrics::ReportRenderCall() {
+  if (!last_call_was_render_) {
+    // If the previous call was a capture and a proper call has been observed
+    // (containing both render and capture data), storing the last number of
+    // capture calls into the metrics.
+    if (proper_call_observed_) {
+      capture_jitter_.Update(num_api_calls_in_a_row_);
+    }
+
+    // Reset the call counter to start counting render calls.
+    num_api_calls_in_a_row_ = 0;
+  }
+  ++num_api_calls_in_a_row_;
+  last_call_was_render_ = true;
+}
+
+void ApiCallJitterMetrics::ReportCaptureCall() {
+  if (last_call_was_render_) {
+    // If the previous call was a render and a proper call has been observed
+    // (containing both render and capture data), storing the last number of
+    // render calls into the metrics.
+    if (proper_call_observed_) {
+      render_jitter_.Update(num_api_calls_in_a_row_);
+    }
+    // Reset the call counter to start counting capture calls.
+    num_api_calls_in_a_row_ = 0;
+
+    // If this statement is reached, at least one render and one capture call
+    // have been observed.
+    proper_call_observed_ = true;
+  }
+  ++num_api_calls_in_a_row_;
+  last_call_was_render_ = false;
+
+  // Only report and update jitter metrics for when a proper call, containing
+  // both render and capture data, has been observed.
+  if (proper_call_observed_ &&
+      TimeToReportMetrics(++frames_since_last_report_)) {
+    // Report jitter, where the base basic unit is frames.
+    constexpr int kMaxJitterToReport = 50;
+
+    // Report max and min jitter for render and capture, in units of 20 ms.
+    RTC_HISTOGRAM_COUNTS_LINEAR(
+        "WebRTC.Audio.EchoCanceller.MaxRenderJitter",
+        std::min(kMaxJitterToReport, render_jitter().max()), 1,
+        kMaxJitterToReport, kMaxJitterToReport);
+    RTC_HISTOGRAM_COUNTS_LINEAR(
+        "WebRTC.Audio.EchoCanceller.MinRenderJitter",
+        std::min(kMaxJitterToReport, render_jitter().min()), 1,
+        kMaxJitterToReport, kMaxJitterToReport);
+
+    RTC_HISTOGRAM_COUNTS_LINEAR(
+        "WebRTC.Audio.EchoCanceller.MaxCaptureJitter",
+        std::min(kMaxJitterToReport, capture_jitter().max()), 1,
+        kMaxJitterToReport, kMaxJitterToReport);
+    RTC_HISTOGRAM_COUNTS_LINEAR(
+        "WebRTC.Audio.EchoCanceller.MinCaptureJitter",
+        std::min(kMaxJitterToReport, capture_jitter().min()), 1,
+        kMaxJitterToReport, kMaxJitterToReport);
+
+    frames_since_last_report_ = 0;
+    Reset();
+  }
+}
+
+bool ApiCallJitterMetrics::WillReportMetricsAtNextCapture() const {
+  return TimeToReportMetrics(frames_since_last_report_ + 1);
+}
+
+}  // namespace webrtc

modules/audio_processing/aec3/api_call_jitter_metrics.h

@@ -0,0 +1,60 @@
+/*
+ *  Copyright (c) 2018 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.
+ */
+
+#ifndef MODULES_AUDIO_PROCESSING_AEC3_API_CALL_JITTER_METRICS_H_
+#define MODULES_AUDIO_PROCESSING_AEC3_API_CALL_JITTER_METRICS_H_
+
+namespace webrtc {
+
+// Stores data for reporting metrics on the API call jitter.
+class ApiCallJitterMetrics {
+ public:
+  class Jitter {
+   public:
+    Jitter();
+    void Update(int num_api_calls_in_a_row);
+    void Reset();
+
+    int min() const { return min_; }
+    int max() const { return max_; }
+
+   private:
+    int max_;
+    int min_;
+  };
+
+  ApiCallJitterMetrics() { Reset(); }
+
+  // Update metrics for render API call.
+  void ReportRenderCall();
+
+  // Update and periodically report metrics for capture API call.
+  void ReportCaptureCall();
+
+  // Methods used only for testing.
+  const Jitter& render_jitter() const { return render_jitter_; }
+  const Jitter& capture_jitter() const { return capture_jitter_; }
+  bool WillReportMetricsAtNextCapture() const;
+
+ private:
+  void Reset();
+
+  Jitter render_jitter_;
+  Jitter capture_jitter_;
+
+  int num_api_calls_in_a_row_ = 0;
+  int frames_since_last_report_ = 0;
+  bool last_call_was_render_ = false;
+  bool proper_call_observed_ = false;
+};
+
+}  // namespace webrtc
+
+#endif  // MODULES_AUDIO_PROCESSING_AEC3_API_CALL_JITTER_METRICS_H_

modules/audio_processing/aec3/api_call_jitter_metrics_unittest.cc

@@ -0,0 +1,109 @@
+/*
+ *  Copyright (c) 2018 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/aec3/api_call_jitter_metrics.h"
+#include "modules/audio_processing/aec3/aec3_common.h"
+
+#include "test/gtest.h"
+
+namespace webrtc {
+
+// Verify constant jitter.
+TEST(ApiCallJitterMetrics, ConstantJitter) {
+  for (int jitter = 1; jitter < 20; ++jitter) {
+    ApiCallJitterMetrics metrics;
+    for (size_t k = 0; k < 30 * kNumBlocksPerSecond; ++k) {
+      for (int j = 0; j < jitter; ++j) {
+        metrics.ReportRenderCall();
+      }
+
+      for (int j = 0; j < jitter; ++j) {
+        metrics.ReportCaptureCall();
+
+        if (metrics.WillReportMetricsAtNextCapture()) {
+          EXPECT_EQ(jitter, metrics.render_jitter().min());
+          EXPECT_EQ(jitter, metrics.render_jitter().max());
+          EXPECT_EQ(jitter, metrics.capture_jitter().min());
+          EXPECT_EQ(jitter, metrics.capture_jitter().max());
+        }
+      }
+    }
+  }
+}
+
+// Verify peaky jitter for the render.
+TEST(ApiCallJitterMetrics, JitterPeakRender) {
+  constexpr int kMinJitter = 2;
+  constexpr int kJitterPeak = 10;
+  constexpr int kPeakInterval = 100;
+
+  ApiCallJitterMetrics metrics;
+  int render_surplus = 0;
+
+  for (size_t k = 0; k < 30 * kNumBlocksPerSecond; ++k) {
+    const int num_render_calls =
+        k % kPeakInterval == 0 ? kJitterPeak : kMinJitter;
+    for (int j = 0; j < num_render_calls; ++j) {
+      metrics.ReportRenderCall();
+      ++render_surplus;
+    }
+
+    ASSERT_LE(kMinJitter, render_surplus);
+    const int num_capture_calls =
+        render_surplus == kMinJitter ? kMinJitter : kMinJitter + 1;
+    for (int j = 0; j < num_capture_calls; ++j) {
+      metrics.ReportCaptureCall();
+
+      if (metrics.WillReportMetricsAtNextCapture()) {
+        EXPECT_EQ(kMinJitter, metrics.render_jitter().min());
+        EXPECT_EQ(kJitterPeak, metrics.render_jitter().max());
+        EXPECT_EQ(kMinJitter, metrics.capture_jitter().min());
+        EXPECT_EQ(kMinJitter + 1, metrics.capture_jitter().max());
+      }
+      --render_surplus;
+    }
+  }
+}
+
+// Verify peaky jitter for the capture.
+TEST(ApiCallJitterMetrics, JitterPeakCapture) {
+  constexpr int kMinJitter = 2;
+  constexpr int kJitterPeak = 10;
+  constexpr int kPeakInterval = 100;
+
+  ApiCallJitterMetrics metrics;
+  int capture_surplus = kMinJitter;
+
+  for (size_t k = 0; k < 30 * kNumBlocksPerSecond; ++k) {
+    ASSERT_LE(kMinJitter, capture_surplus);
+    const int num_render_calls =
+        capture_surplus == kMinJitter ? kMinJitter : kMinJitter + 1;
+    for (int j = 0; j < num_render_calls; ++j) {
+      metrics.ReportRenderCall();
+      --capture_surplus;
+    }
+
+    const int num_capture_calls =
+        k % kPeakInterval == 0 ? kJitterPeak : kMinJitter;
+    for (int j = 0; j < num_capture_calls; ++j) {
+      metrics.ReportCaptureCall();
+
+      if (metrics.WillReportMetricsAtNextCapture()) {
+        EXPECT_EQ(kMinJitter, metrics.render_jitter().min());
+        EXPECT_EQ(kMinJitter + 1, metrics.render_jitter().max());
+        EXPECT_EQ(kMinJitter, metrics.capture_jitter().min());
+        EXPECT_EQ(kJitterPeak, metrics.capture_jitter().max());
+      }
+      ++capture_surplus;
+    }
+  }
+}
+
+}  // namespace webrtc

modules/audio_processing/aec3/echo_canceller3.cc

@@ -446,6 +446,10 @@ void EchoCanceller3::ProcessCapture(AudioBuffer* capture, bool level_change) {
   data_dumper_->DumpRaw("aec3_call_order",
                         static_cast<int>(EchoCanceller3ApiCall::kCapture));
 
+  // Report capture call in the metrics and periodically update API call
+  // metrics.
+  api_call_metrics_.ReportCaptureCall();
+
   // Optionally delay the capture signal.
   if (config_.delay.fixed_capture_delay_samples > 0) {
     block_delay_buffer_.DelaySignal(capture);
@@ -500,6 +504,9 @@ void EchoCanceller3::EmptyRenderQueue() {
   bool frame_to_buffer =
       render_transfer_queue_.Remove(&render_queue_output_frame_);
   while (frame_to_buffer) {
+    // Report render call in the metrics.
+    api_call_metrics_.ReportRenderCall();
+
     BufferRenderFrameContent(&render_queue_output_frame_, 0, &render_blocker_,
                              block_processor_.get(), &block_, &sub_frame_view_);
 

modules/audio_processing/aec3/echo_canceller3.h

@@ -18,6 +18,7 @@
 #include "api/array_view.h"
 #include "api/audio/echo_canceller3_config.h"
 #include "api/audio/echo_control.h"
+#include "modules/audio_processing/aec3/api_call_jitter_metrics.h"
 #include "modules/audio_processing/aec3/block_delay_buffer.h"
 #include "modules/audio_processing/aec3/block_framer.h"
 #include "modules/audio_processing/aec3/block_processor.h"
@@ -140,6 +141,7 @@ class EchoCanceller3 : public EchoControl {
   std::vector<rtc::ArrayView<float>> sub_frame_view_
       RTC_GUARDED_BY(capture_race_checker_);
   BlockDelayBuffer block_delay_buffer_ RTC_GUARDED_BY(capture_race_checker_);
+  ApiCallJitterMetrics api_call_metrics_ RTC_GUARDED_BY(capture_race_checker_);
 
   RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(EchoCanceller3);
 };