Allow more than 2 input channels in AudioProcessing.

webrtc/modules/audio_processing/include/audio_processing.h

 /*
  *  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.
  */
 
@@ skipping 11 matching lines @@
 
 struct AecCore;
 
 namespace webrtc {
 
 class AudioFrame;
 
 template<typename T>
 class Beamformer;
 
+class StreamConfig;
+class ProcessingConfig;
+
 class EchoCancellation;
 class EchoControlMobile;
 class GainControl;
 class HighPassFilter;
 class LevelEstimator;
 class NoiseSuppression;
 class VoiceDetection;
 
 // Use to enable the extended filter mode in the AEC, along with robustness
 // measures around the reported system delays. It comes with a significant
@@ skipping 35 matching lines @@
 // [12, 255]. Here, 255 maps to 100%.
 //
 // Must be provided through AudioProcessing::Create(Confg&).
 #if defined(WEBRTC_CHROMIUM_BUILD)
 static const int kAgcStartupMinVolume = 85;
 #else
 static const int kAgcStartupMinVolume = 0;
 #endif  // defined(WEBRTC_CHROMIUM_BUILD)
 struct ExperimentalAgc {
   ExperimentalAgc() : enabled(true), startup_min_volume(kAgcStartupMinVolume) {}
-  ExperimentalAgc(bool enabled)
+  explicit ExperimentalAgc(bool enabled)
       : enabled(enabled), startup_min_volume(kAgcStartupMinVolume) {}
   ExperimentalAgc(bool enabled, int startup_min_volume)
       : enabled(enabled), startup_min_volume(startup_min_volume) {}
   bool enabled;
   int startup_min_volume;
 };
 
 // Use to enable experimental noise suppression. It can be set in the
 // constructor or using AudioProcessing::SetExtraOptions().
 struct ExperimentalNs {
@@ skipping 131 matching lines @@
   //
   // It is also not necessary to call if the audio parameters (sample
   // rate and number of channels) have changed. Passing updated parameters
   // directly to |ProcessStream()| and |AnalyzeReverseStream()| is permissible.
   // If the parameters are known at init-time though, they may be provided.
   virtual int Initialize() = 0;
 
   // The int16 interfaces require:
   //   - only |NativeRate|s be used
   //   - that the input, output and reverse rates must match
-  //   - that |output_layout| matches |input_layout|
+  //   - that |processing_config.output_stream()| matches
+  //     |processing_config.input_stream()|.
   //
-  // The float interfaces accept arbitrary rates and support differing input
-  // and output layouts, but the output may only remove channels, not add.
+  // The float interfaces accept arbitrary rates and support differing input and
+  // output layouts, but the output must have either one channel or the same
+  // number of channels as the input.
+  virtual int Initialize(const ProcessingConfig& processing_config) = 0;
+
+  // Initialize with unpacked parameters. See Initialize() above for details.
   virtual int Initialize(int input_sample_rate_hz,
                          int output_sample_rate_hz,
                          int reverse_sample_rate_hz,
                          ChannelLayout input_layout,
                          ChannelLayout output_layout,
                          ChannelLayout reverse_layout) = 0;
 
   // Pass down additional options which don't have explicit setters. This
   // ensures the options are applied immediately.
   virtual void SetExtraOptions(const Config& config) = 0;
@@ skipping 32 matching lines @@
   // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
   // members of |frame| must be valid. If changed from the previous call to this
   // method, it will trigger an initialization.
   virtual int ProcessStream(AudioFrame* frame) = 0;
 
   // Accepts deinterleaved float audio with the range [-1, 1]. Each element
   // of |src| points to a channel buffer, arranged according to
   // |input_layout|. At output, the channels will be arranged according to
   // |output_layout| at |output_sample_rate_hz| in |dest|.
   //
-  // The output layout may only remove channels, not add. |src| and |dest|
-  // may use the same memory, if desired.
+  // The output layout must have one channel or as many channels as the input.
+  // |src| and |dest| may use the same memory, if desired.
   virtual int ProcessStream(const float* const* src,

[ajm, 2015/07/15 05:21:20]

Can you add a TODO here and on the deprecated AnalyzeReverseStream to remove
when clients are updated?

[mgraczyk, 2015/07/15 20:03:20]

Done.

                             int samples_per_channel,
                             int input_sample_rate_hz,
                             ChannelLayout input_layout,
                             int output_sample_rate_hz,
                             ChannelLayout output_layout,
                             float* const* dest) = 0;
 
+  // Accepts deinterleaved float audio with the range [-1, 1]. Each element of
+  // |src| points to a channel buffer, arranged according to
+  // |processing_config.input_stream()|. At output, the channels will be
+  // arranged according to |processing_config.output_stream()| in |dest|.
+  //
+  // The output must have one channel or as many channels as the input. |src|
+  // and |dest| may use the same memory, if desired.
+  virtual int ProcessStream(const float* const* src,
+                            const ProcessingConfig& processing_config,
+                            float* const* dest) = 0;
+
   // Analyzes a 10 ms |frame| of the reverse direction audio stream. The frame
   // will not be modified. On the client-side, this is the far-end (or to be
   // rendered) audio.
   //
   // It is only necessary to provide this if echo processing is enabled, as the
   // reverse stream forms the echo reference signal. It is recommended, but not
   // necessary, to provide if gain control is enabled. On the server-side this
   // typically will not be used. If you're not sure what to pass in here,
   // chances are you don't need to use it.
   //
   // The |sample_rate_hz_|, |num_channels_|, and |samples_per_channel_|
   // members of |frame| must be valid. |sample_rate_hz_| must correspond to
   // |input_sample_rate_hz()|
   //
   // TODO(ajm): add const to input; requires an implementation fix.
   virtual int AnalyzeReverseStream(AudioFrame* frame) = 0;
 
   // Accepts deinterleaved float audio with the range [-1, 1]. Each element
   // of |data| points to a channel buffer, arranged according to |layout|.
   virtual int AnalyzeReverseStream(const float* const* data,
                                    int samples_per_channel,
                                    int sample_rate_hz,
                                    ChannelLayout layout) = 0;
 
+  // Accepts deinterleaved float audio with the range [-1, 1]. Each element of
+  // |data| points to a channel buffer, arranged according to |reverse_config|.
+  virtual int AnalyzeReverseStream(const float* const* data,
+                                   const StreamConfig& reverse_config) = 0;
+
   // This must be called if and only if echo processing is enabled.
   //
   // Sets the |delay| in ms between AnalyzeReverseStream() receiving a far-end
   // frame and ProcessStream() receiving a near-end frame containing the
   // corresponding echo. On the client-side this can be expressed as
   //   delay = (t_render - t_analyze) + (t_process - t_capture)
   // where,
   //   - t_analyze is the time a frame is passed to AnalyzeReverseStream() and
   //     t_render is the time the first sample of the same frame is rendered by
   //     the audio hardware.
@@ skipping 86 matching lines @@
   enum NativeRate {
     kSampleRate8kHz = 8000,
     kSampleRate16kHz = 16000,
     kSampleRate32kHz = 32000,
     kSampleRate48kHz = 48000
   };
 
   static const int kChunkSizeMs = 10;
 };
 
+class StreamConfig {
+ public:
+  StreamConfig(int sample_rate_hz = 0,
+               int num_channels = 0,
+               bool has_keyboard = false)
+      : sample_rate_hz_(sample_rate_hz),
+        num_channels_(num_channels),
+        has_keyboard_(has_keyboard),
+        samples_per_channel_(calculate_samples_per_channel(sample_rate_hz)) {}

[ajm, 2015/07/15 05:21:20]

Alex, Michael: I know it breaks convention in this module, but what do you think
about using num_frames_ to represent this quantity? We've been switching
elsewhere.

[aluebs-webrtc, 2015/07/15 16:42:17]

It is unfortunate that we used "frames" to refer to blocks/chunks in other
places, so I find the term "frames" really confusing. But now that we have a
convention, I think we should stick with it for all new code. In short, I agree
it is probably for the best to use num_frames_.

[mgraczyk, 2015/07/15 20:03:20]

Done, although I think there are plenty of better names.  "frames_per_chunk_",
"frames_per_channel_", "chunk_size_frames_", or what we have now would all be
more clear.

+
+  void set_sample_rate_hz(int value) {
+    sample_rate_hz_ = value;
+    samples_per_channel_ = calculate_samples_per_channel(value);
+  }
+  void set_num_channels(int value) { num_channels_ = value; }
+  void set_has_keyboard(bool value) { has_keyboard_ = value; }
+
+  int sample_rate_hz() const { return sample_rate_hz_; }
+  int num_channels() const { return num_channels_; }
+  bool has_keyboard() const { return has_keyboard_; }
+  int samples_per_channel() const { return samples_per_channel_; }
+
+  bool operator==(const StreamConfig& other) const {
+    return sample_rate_hz_ == other.sample_rate_hz_ &&
+           num_channels_ == other.num_channels_ &&
+           has_keyboard_ == other.has_keyboard_;
+  }
+
+  bool operator!=(const StreamConfig& other) const { return !(*this == other); }
+
+ private:
+  static int calculate_samples_per_channel(int sample_rate_hz) {
+    return AudioProcessing::kChunkSizeMs * sample_rate_hz / 1000;
+  }
+
+  int sample_rate_hz_;
+  int num_channels_;
+  bool has_keyboard_;
+  int samples_per_channel_;
+};
+
+class ProcessingConfig {
+ public:
+  enum StreamName {
+    kInputStream,
+    kOutputStream,
+    kReverseStream,
+    kNumStreamNames,
+  };
+
+  const StreamConfig& input_stream() const {
+    return streams[StreamName::kInputStream];
+  }
+  const StreamConfig& output_stream() const {
+    return streams[StreamName::kOutputStream];
+  }
+  const StreamConfig& reverse_stream() const {
+    return streams[StreamName::kReverseStream];
+  }
+
+  StreamConfig& input_stream() {
+    return streams[StreamName::kInputStream];
+  }
+  StreamConfig& output_stream() {
+    return streams[StreamName::kOutputStream];
+  }
+  StreamConfig& reverse_stream() {
+    return streams[StreamName::kReverseStream];
+  }
+
+  bool operator==(const ProcessingConfig& other) const {
+    for (int i = 0; i < StreamName::kNumStreamNames; ++i) {
+      if (this->streams[i] != other.streams[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  bool operator!=(const ProcessingConfig& other) const {
+    return !(*this == other);
+  }
+
+  StreamConfig streams[StreamName::kNumStreamNames];
+};
+
 // The acoustic echo cancellation (AEC) component provides better performance
 // than AECM but also requires more processing power and is dependent on delay
 // stability and reporting accuracy. As such it is well-suited and recommended
 // for PC and IP phone applications.
 //
 // Not recommended to be enabled on the server-side.
 class EchoCancellation {
  public:
   // EchoCancellation and EchoControlMobile may not be enabled simultaneously.
   // Enabling one will disable the other.
@@ skipping 342 matching lines @@
   // This does not impact the size of frames passed to |ProcessStream()|.
   virtual int set_frame_size_ms(int size) = 0;
   virtual int frame_size_ms() const = 0;
 
  protected:
   virtual ~VoiceDetection() {}
 };
 }  // namespace webrtc
 
 #endif  // WEBRTC_MODULES_AUDIO_PROCESSING_INCLUDE_AUDIO_PROCESSING_H_