AecDump interface

webrtc/modules/audio_processing/include/aec_dump.h

Index: webrtc/modules/audio_processing/include/aec_dump.h
diff --git a/webrtc/modules/audio_processing/include/aec_dump.h b/webrtc/modules/audio_processing/include/aec_dump.h
new file mode 100644
index 0000000000000000000000000000000000000000..298ee04df68268b435e401d06073186aebecb39d
--- /dev/null
+++ b/webrtc/modules/audio_processing/include/aec_dump.h
@@ -0,0 +1,145 @@
+/*
+ *  Copyright (c) 2017 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 WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AEC_DUMP_H_
+#define WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AEC_DUMP_H_
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "webrtc/base/array_view.h"
+
+namespace webrtc {
+
+class AudioFrame;
+
+// Struct for passing current config from APM without having to
+// include protobuf headers.
+struct InternalAPMConfig {
+  InternalAPMConfig();
+  InternalAPMConfig(const InternalAPMConfig&);
+  InternalAPMConfig(InternalAPMConfig&&);
+
+  InternalAPMConfig& operator=(const InternalAPMConfig&) = delete;
+  InternalAPMConfig& operator=(const InternalAPMConfig&&) = delete;
+
+  bool aec_enabled = false;
+  bool aec_delay_agnostic_enabled = false;
+  bool aec_drift_compensation_enabled = false;
+  bool aec_extended_filter_enabled = false;
+  int aec_suppression_level = 0;
+  bool aecm_enabled = false;
+  bool aecm_comfort_noise_enabled = false;
+  int aecm_routing_mode = 0;
+  bool agc_enabled = false;
+  int agc_mode = 0;
+  bool agc_limiter_enabled = false;
+  bool hpf_enabled = false;
+  bool ns_enabled = false;
+  int ns_level = 0;
+  bool transient_suppression_enabled = false;
+  bool intelligibility_enhancer_enabled = false;
+  bool noise_robust_agc_enabled = false;
+  std::string experiments_description = "";
+};
+
+struct InternalAPMStreamsConfig {
+  int input_sample_rate = 0;
+  int output_sample_rate = 0;
+  int render_input_sample_rate = 0;
+  int render_output_sample_rate = 0;
+
+  size_t input_num_channels = 0;
+  size_t output_num_channels = 0;
+  size_t render_input_num_channels = 0;
+  size_t render_output_num_channels = 0;
+};
+
+// Class to pass audio data in float** format. This is to avoid
+// dependence on AudioBuffer, and avoid problems associated with
+// rtc::ArrayView<rtc::ArrayView>.
+class FloatAudioFrame {
+ public:
+  FloatAudioFrame(const float* const* audio_samples,
+                  size_t num_channels,
+                  size_t channel_size)

[kwiberg-webrtc, 2017/05/03 18:57:57]

These are nontrivial arguments. Document them?

[aleloi, 2017/05/04 08:56:40]

Done.

+      : audio_samples_(audio_samples),
+        num_channels_(num_channels),
+        channel_size_(channel_size) {}
+
+  size_t num_channels() const { return num_channels_; }
+
+  rtc::ArrayView<const float> channel(size_t idx) const {
+    RTC_DCHECK_LE(0, idx);
+    RTC_DCHECK_LE(idx, num_channels_);
+    return rtc::ArrayView<const float>(audio_samples_[idx], channel_size_);
+  }
+
+ private:
+  const float* const* audio_samples_;
+  size_t num_channels_;
+  size_t channel_size_;
+};

[kwiberg-webrtc, 2017/05/03 18:57:57]

This is exactly what I had in mind when we spoke: a simple value class that
hides its members and provides safe accessors.

+
+// An interface for recording configuration and input/output streams
+// of the Audio Processing Module. The recordings are called
+// 'aec-dumps' and are stored in a protobuf format defined in
+// debug.proto.
+class AecDump {
+ public:
+  // A capture stream frame is logged before and after processing in
+  // the same protobuf message. To facilitate that, a CaptureStreamInfo
+  // instance is first filled with Input, then Output.
+  //
+  // To log an input/output pair, first call
+  // AecDump::GetCaptureStreamInfo.  Add the input and output to
+  // it. Then call AecDump::WriteCaptureStreamMessage.
+  class CaptureStreamInfo {
+   public:
+    virtual ~CaptureStreamInfo() = default;
+    virtual void AddInput(FloatAudioFrame src) = 0;

[peah-webrtc, 2017/05/04 06:19:08]

These calls are made by copying the FloatAudioFrame objects. Even though those
are small, I guess it would be faster to const-ref them? Or is it better for the
compiler to have them copied? If not for complexity, it may be good for the
reader of the code as at a casual look at the code it looks as if these objects
are large (A FloatAudioFrame looks like a container for a frame of samples).

[aleloi, 2017/05/04 08:56:40]

I think no copies are made here because of return value optimization rules. I've
changed to const-ref for it to read better.

+    virtual void AddOutput(FloatAudioFrame src) = 0;
+
+    virtual void AddInput(const AudioFrame& frame) = 0;
+    virtual void AddOutput(const AudioFrame& frame) = 0;
+
+    virtual void set_delay(int delay) = 0;
+    virtual void set_drift(int drift) = 0;

[peah-webrtc, 2017/05/04 06:19:08]

I think it would make sense to combine these 4 setters into a single set method
as they are alway called at the same time, that will avoid missing calling one
of them by mistake, and cause the code to be smaller. WDYT?

[aleloi, 2017/05/04 08:56:40]

I think a set_state(int, int, int, bool) method would harm readability. WDYT re
adding a AECState{delay, drift, level, keypress} struct (which can have setters,
but the setters would not be virtual and be inlined) and a set_state(const
AECState &) method? That would follow the recommendations in
https://google.github.io/styleguide/cppguide.html#Implementation_Comments 

[peah-webrtc, 2017/05/04 10:57:51]

I don't think the style guide comment really applies to reducing the number of
parameters in general but rather to commenting code, but I may be wrong. For
readability I prefer shorter code, and replacing multi-parameter methods with
several single parameters produces more code, both for making the calls as well
as for implementing the setters (more boilerplate code).

In this case I think it is ok to have it as it is as I think your point about
the explicit documentation about what is logged is a really strong one.

Regarding the AECState, I'd prefer instead avoiding making
AecDump::CaptureStreamInfo an interface. With that change, the setters won't be
virtual, which means that they can be inlined and the cpu-overhead will be
nonexistent.

+    virtual void set_level(int level) = 0;
+    virtual void set_keypress(bool keypress) = 0;
+  };
+
+  virtual ~AecDump() = default;
+
+  virtual std::unique_ptr<CaptureStreamInfo> GetCaptureStreamInfo() const = 0;

[peah-webrtc, 2017/05/04 06:19:08]

Does the GetCaptureStreamInfo() method create CaptureStream Objects?

[aleloi, 2017/05/04 08:56:40]

Yes, it should be called 'CreateCaptureStreamInfo'. Now renamed.

+
+  // The Write* methods are always safe to call concurrently or
+  // otherwise for all implementing subclasses. The intended mode of
+  // operation is to create a protobuf object from the input, and send
+  // it away to be written to file asynchronously.
+  virtual void WriteInitMessage(
+      const InternalAPMStreamsConfig& streams_config) = 0;
+
+  virtual void WriteRenderStreamMessage(const AudioFrame& frame) = 0;
+
+  virtual void WriteRenderStreamMessage(FloatAudioFrame src) = 0;
+
+  virtual void WriteCaptureStreamMessage(
+      std::unique_ptr<CaptureStreamInfo> stream_info) = 0;
+
+  // If not |forced|, only writes the current config if it is
+  // different from the last saved one; if |forced|, writes the config
+  // regardless of the last saved.
+  virtual void WriteConfig(const InternalAPMConfig& config, bool forced) = 0;
+};
+}  // namespace webrtc
+
+#endif  // WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AEC_DUMP_H_