Added first layer of the echo canceller 3 functionality

webrtc/modules/audio_processing/aec3/echo_canceller3.h

 /*
  *  Copyright (c) 2016 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_AEC3_ECHO_CANCELLER3_H_
 #define WEBRTC_MODULES_AUDIO_PROCESSING_AEC3_ECHO_CANCELLER3_H_
 
-#include <string>
-
 #include "webrtc/base/constructormagic.h"
+#include "webrtc/modules/audio_processing/aec3/block_framer.h"
+#include "webrtc/modules/audio_processing/aec3/block_processor.h"
+#include "webrtc/modules/audio_processing/aec3/cascaded_biquad_filter.h"
+#include "webrtc/modules/audio_processing/aec3/frame_blocker.h"
+#include "webrtc/modules/audio_processing/aec3/render_transfer_buffer.h"
 #include "webrtc/modules/audio_processing/audio_buffer.h"
+#include "webrtc/modules/audio_processing/include/audio_processing.h"
+#include "webrtc/modules/audio_processing/logging/apm_data_dumper.h"
 
 namespace webrtc {
 
+// Main class for the echo canceller3. It does 4 things:
+// -Receives 10 ms frames of band-split audio.
+// -Optionally applies an anti-hum (high-pass) filter on the
+// received signals.
+// -Provides the lower level echo canceller functionality with
+// blocks of 64 samples of audio data.
+// -Partially handles the jitter in the render and capture API
+// call sequence.
+// The class is supposed to be used in a single-threaded manner

[hlundin-webrtc, 2016/12/16 10:04:47]

What does single-threaded mean here? Should all methods except AnalyzeRender be
called from the same thread, or just not at the same time? Is there anything
that enforces this design?

[peah-webrtc, 2016/12/20 10:10:25]

Good point. I changed the comment to be more clear (I think). What I mean is not
single-threadedness but rather concurrent calling. 

There is nothing that enforces this, and I'm not sure that we should do that. I
don't want to add a lock just to ensure that the class in not used in the
correct manner. 

The thing is, the echo canceller is not intended for cuncurrent usage, apart
from the AnalyzeRender call. That call is safe as it does not use any common
resources with the rest of the code, apart from the SwapQueue which is thread
safe.


WDYT?

[hlundin-webrtc, 2016/12/20 15:10:34]

I propose you use a RaceChecker, similarly to how it is used in
audio_mixer_impl.{cc,h}. You will then need two RaceChecker members in the
state; one for capture and one for render. Then you should annotate all state
variables except the SwapQueue with the correct GUARDED_BY. Finally, use
RTC_DCHECK_RUNS_SERIALIZED with the correct RaceChecker member in each method.

[peah-webrtc, 2016/12/21 23:13:48]

I agree!
Done.

+// apart from the AnalyzeRender call which can be performed
+// from another thread.
 class EchoCanceller3 {
  public:
-  EchoCanceller3(int sample_rate_hz, bool use_anti_hum_filter);
+  EchoCanceller3(int sample_rate_hz, bool use_highpass_filter);
   ~EchoCanceller3();
   // Analyzes and stores an internal copy of the split-band domain render
   // signal.
   bool AnalyzeRender(AudioBuffer* farend);
   // Analyzes the full-band domain capture signal to detect signal saturation.
   void AnalyzeCapture(AudioBuffer* capture);
   // Processes the split-band domain capture signal in order to remove any echo
   // present in the signal.
   void ProcessCapture(AudioBuffer* capture, bool known_echo_path_change);
 
+  // Signals whether an external detector has detected echo leakage from the
+  // echo canceller.
+  // Note that in the case echo leakage has been flagged, it should be unflagged
+  // once it is no longer occurring.
+  void ReportEchoLeakage(bool leakage_detected) {
+    block_processor_.ReportEchoLeakage(leakage_detected);
+  }
+
   // Validates a config.
   static bool Validate(const AudioProcessing::Config::EchoCanceller3& config);
   // Dumps a config to a string.
   static std::string ToString(
       const AudioProcessing::Config::EchoCanceller3& config);
 
  private:
+  class RenderWriterState {

[hlundin-webrtc, 2016/12/16 10:04:47]

"State" suggests that this is a simple data container, but it is more than that.
Consider renaming to RenderWriter.

[ivoc, 2016/12/19 11:30:22]

Since this class is private and EchoCanceller3 only has a unique_ptr to it, I
think you can move the implementation to the .cc file and put a forward
declaration in the header.

[peah-webrtc, 2016/12/20 10:10:25]

Good point!
Done.

[peah-webrtc, 2016/12/20 10:10:25]

Done.

+   public:
+    RenderWriterState(
+        ApmDataDumper* data_dumper,
+        RenderTransferBufferWriter* transfer_buffer_writer,
+        std::unique_ptr<CascadedBiQuadFilter> render_highpass_filter,
+        int sample_rate_hz,
+        int frame_length,
+        int num_bands);
+    ~RenderWriterState();
+    bool Insert(AudioBuffer* render);
+
+   private:
+    ApmDataDumper* data_dumper_;
+    const int sample_rate_hz_;
+    const size_t frame_length_;
+    const int num_bands_;
+    RenderTransferBufferWriter* transfer_buffer_writer_;
+    std::unique_ptr<CascadedBiQuadFilter> render_highpass_filter_;
+    std::vector<float> render_queue_input_frame_;
+    RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(RenderWriterState);
+  };
+  // State that may be accessed by the render thread.
+  std::unique_ptr<RenderWriterState> render_writer_;
+
+  // State that may be accessed by the capture thread.
   static int instance_count_;
-  size_t frame_length_;
+  std::unique_ptr<ApmDataDumper> data_dumper_;
+  const int sample_rate_hz_;
+  const int num_bands_;
+  const size_t frame_length_;
+  BlockFramer output_framer_;
+  FrameBlocker capture_blocker_;
+  FrameBlocker render_blocker_;
+  RenderTransferBuffer render_transfer_buffer_;
+  BlockProcessor block_processor_;
+  std::vector<float> render_queue_output_frame_;
+  std::unique_ptr<CascadedBiQuadFilter> capture_highpass_filter_;
+  bool saturated_microphone_signal_ = false;
+  bool EmptyRenderQueue();

[hlundin-webrtc, 2016/12/16 10:04:47]

Declare methods before data members.
https://google.github.io/styleguide/cppguide.html#Declaration_Order

[peah-webrtc, 2016/12/20 10:10:25]

Done.

 
   RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(EchoCanceller3);
 };
 }  // namespace webrtc
 
 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_AEC3_ECHO_CANCELLER3_H_