1 /*
2  *  Copyright (c) 2016 The WebRTC project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 #ifndef MODULES_AUDIO_PROCESSING_AEC3_ECHO_CANCELLER3_H_
12 #define MODULES_AUDIO_PROCESSING_AEC3_ECHO_CANCELLER3_H_
13 
14 #include "modules/audio_processing/aec3/block_framer.h"
15 #include "modules/audio_processing/aec3/block_processor.h"
16 #include "modules/audio_processing/aec3/cascaded_biquad_filter.h"
17 #include "modules/audio_processing/aec3/frame_blocker.h"
18 #include "modules/audio_processing/audio_buffer.h"
19 #include "modules/audio_processing/include/audio_processing.h"
20 #include "modules/audio_processing/logging/apm_data_dumper.h"
21 #include "rtc_base/constructormagic.h"
22 #include "rtc_base/race_checker.h"
23 #include "rtc_base/swap_queue.h"
24 
25 namespace webrtc {
26 
27 // Functor for verifying the invariance of the frames being put into the render
28 // queue.
29 class Aec3RenderQueueItemVerifier {
30  public:
Aec3RenderQueueItemVerifier(size_t num_bands,size_t frame_length)31   explicit Aec3RenderQueueItemVerifier(size_t num_bands, size_t frame_length)
32       : num_bands_(num_bands), frame_length_(frame_length) {}
33 
operator()34   bool operator()(const std::vector<std::vector<float>>& v) const {
35     if (v.size() != num_bands_) {
36       return false;
37     }
38     for (const auto& v_k : v) {
39       if (v_k.size() != frame_length_) {
40         return false;
41       }
42     }
43     return true;
44   }
45 
46  private:
47   const size_t num_bands_;
48   const size_t frame_length_;
49 };
50 
51 // Main class for the echo canceller3.
52 // It does 4 things:
53 // -Receives 10 ms frames of band-split audio.
54 // -Optionally applies an anti-hum (high-pass) filter on the
55 // received signals.
56 // -Provides the lower level echo canceller functionality with
57 // blocks of 64 samples of audio data.
58 // -Partially handles the jitter in the render and capture API
59 // call sequence.
60 //
61 // The class is supposed to be used in a non-concurrent manner apart from the
62 // AnalyzeRender call which can be called concurrently with the other methods.
63 class EchoCanceller3 : public EchoControl {
64  public:
65   // Normal c-tor to use.
66   EchoCanceller3(const EchoCanceller3Config& config,
67                  int sample_rate_hz,
68                  bool use_highpass_filter);
69   // Testing c-tor that is used only for testing purposes.
70   EchoCanceller3(int sample_rate_hz,
71                  bool use_highpass_filter,
72                  std::unique_ptr<BlockProcessor> block_processor);
73   ~EchoCanceller3() override;
74   // Analyzes and stores an internal copy of the split-band domain render
75   // signal.
76   void AnalyzeRender(AudioBuffer* farend) override;
77   // Analyzes the full-band domain capture signal to detect signal saturation.
78   void AnalyzeCapture(AudioBuffer* capture) override;
79   // Processes the split-band domain capture signal in order to remove any echo
80   // present in the signal.
81   void ProcessCapture(AudioBuffer* capture, bool level_change) override;
82   // Collect current metrics from the echo canceller.
83   Metrics GetMetrics() const override;
84 
85   // Signals whether an external detector has detected echo leakage from the
86   // echo canceller.
87   // Note that in the case echo leakage has been flagged, it should be unflagged
88   // once it is no longer occurring.
UpdateEchoLeakageStatus(bool leakage_detected)89   void UpdateEchoLeakageStatus(bool leakage_detected) {
90     RTC_DCHECK_RUNS_SERIALIZED(&capture_race_checker_);
91     block_processor_->UpdateEchoLeakageStatus(leakage_detected);
92   }
93 
94   // Validates a config.
95   static bool Validate(const EchoCanceller3Config& config);
96 
97  private:
98   class RenderWriter;
99 
100   // Empties the render SwapQueue.
101   void EmptyRenderQueue();
102 
103   rtc::RaceChecker capture_race_checker_;
104   rtc::RaceChecker render_race_checker_;
105 
106   // State that is accessed by the AnalyzeRender call.
107   std::unique_ptr<RenderWriter> render_writer_
108       RTC_GUARDED_BY(render_race_checker_);
109 
110   // State that may be accessed by the capture thread.
111   static int instance_count_;
112   std::unique_ptr<ApmDataDumper> data_dumper_;
113   const int sample_rate_hz_;
114   const int num_bands_;
115   const size_t frame_length_;
116   BlockFramer output_framer_ RTC_GUARDED_BY(capture_race_checker_);
117   FrameBlocker capture_blocker_ RTC_GUARDED_BY(capture_race_checker_);
118   FrameBlocker render_blocker_ RTC_GUARDED_BY(capture_race_checker_);
119   SwapQueue<std::vector<std::vector<float>>, Aec3RenderQueueItemVerifier>
120       render_transfer_queue_;
121   std::unique_ptr<BlockProcessor> block_processor_
122       RTC_GUARDED_BY(capture_race_checker_);
123   std::vector<std::vector<float>> render_queue_output_frame_
124       RTC_GUARDED_BY(capture_race_checker_);
125   std::unique_ptr<CascadedBiQuadFilter> capture_highpass_filter_
126       RTC_GUARDED_BY(capture_race_checker_);
127   bool saturated_microphone_signal_ RTC_GUARDED_BY(capture_race_checker_) =
128       false;
129   std::vector<std::vector<float>> block_ RTC_GUARDED_BY(capture_race_checker_);
130   std::vector<rtc::ArrayView<float>> sub_frame_view_
131       RTC_GUARDED_BY(capture_race_checker_);
132 
133   RTC_DISALLOW_IMPLICIT_CONSTRUCTORS(EchoCanceller3);
134 };
135 }  // namespace webrtc
136 
137 #endif  // MODULES_AUDIO_PROCESSING_AEC3_ECHO_CANCELLER3_H_
138