Add support for channel transforms.

media/base/channel_mixer.cc

+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// MSVC++ requires this to be set before any other includes to get M_SQRT1_2.
+#define _USE_MATH_DEFINES
+
+#include "media/base/channel_mixer.h"
+
+#include <algorithm>
+#include <cmath>
+
+#include "base/logging.h"
+#include "media/base/audio_bus.h"
+#include "media/base/vector_math.h"
+
+namespace media {
+
+// Default scale factor for mixing two channels together.  We use a different
+// value for stereo -> mono and mono -> stereo mixes.
+static const float kDefaultScale = static_cast<float>(M_SQRT1_2);

[Chris Rogers, 2012/10/19 20:48:17]

A better name might be kEqualPowerScale

[DaleCurtis, 2012/10/19 22:33:20]

Done.

+
+static int ValidateLayout(ChannelLayout layout) {
+  CHECK_NE(layout, CHANNEL_LAYOUT_NONE);
+  CHECK_NE(layout, CHANNEL_LAYOUT_UNSUPPORTED);
+  CHECK_NE(layout, CHANNEL_LAYOUT_MAX);

[Chris Rogers, 2012/10/19 20:48:17]

Can't we handle the CHANNEL_LAYOUT_UNSUPPORTED case?  We could simply copy
channels in the order they come in, and either drop extra channels or zero out
remaining extra channels.

We should at least add a TODO about this case. 

[DaleCurtis, 2012/10/19 22:33:20]

No, this means the AudioParameters are invalid and channel count == 0 since
you're required to provide a channel layout to construct that object. 
Supporting arbitrary layouts is not something I want to get into here.

[Chris Rogers, 2012/10/19 22:52:26]

We might require that *now*, but this needs to be made more general.

We won't always have a known channel layout.  For the output-side, it's easily
possible on OSX to be connected to a Firewire device outputting say 8, 12, or
whatever channels which have no speaker layout.  They're just raw channels. 
They could be connected to a multi-channel recording device, or connected to a
custom speaker array controlled by WebAudio.  For example, at CCRMA they have
several studios with large speaker arrays on the inside of a geodesic dome. 
These are all custom speaker arrangements, so for our purposes would be
CHANNEL_LAYOUT_UNSUPPORTED, or maybe a better name would be
CHANNEL_LAYOUT_CUSTOM.  And believe me, these guys and others are clamoring to
have this kind of support in Chrome ASAP.

Similarly on the client/input-side, WebAudio might be configured to output
4,5,6,7,13, 17 channels, or whatever which have none of our known layouts, which
can then be custom matrix mixed within WebAudio.

So, in these types of cases the best we can do is simply copy channels from
input to output until we either run out of channels, or there are some remaining
which we zero out.

[DaleCurtis, 2012/10/19 23:14:32]

Sure we definitely want to handle this some day, but until then we do not and
things will not work if someone tries to (even before this CL) so we should just
fail if someone attempts to try this.  Currently this connection will fail in
the AudioOutputController stage because the AudioParameters will be invalid.

I'll can a TODO, but that's not going to magically fix the many other places
that make this impossible right now :)

+
+  // Verify there's at least one channel.  Should always be true here by virtue
+  // of not being one of the invalid layouts, but lets double check to be sure.
+  int channel_count = ChannelLayoutToChannelCount(layout);
+  DCHECK_GT(channel_count, 0);
+
+  // If we have more than one channel, verify a symmetric layout for sanity.
+  // The unit test will verify all possible layouts, so this can be a DCHECK.
+  // Symmetry allows simplifying the matrix building code by allowing us to
+  // assume that if one channel of a pair exists, the other will too.
+  if (channel_count > 1) {
+    DCHECK((ChannelOrder(layout, LEFT) >= 0 &&
+            ChannelOrder(layout, RIGHT) >= 0) ||
+           (ChannelOrder(layout, SIDE_LEFT) >= 0 &&
+            ChannelOrder(layout, SIDE_RIGHT) >= 0) ||
+           (ChannelOrder(layout, BACK_LEFT) >= 0 &&
+            ChannelOrder(layout, BACK_RIGHT) >= 0) ||
+           (ChannelOrder(layout, LEFT_OF_CENTER) >= 0 &&
+            ChannelOrder(layout, RIGHT_OF_CENTER) >= 0))
+        << "Non-symmetric channel layout encountered.";
+  } else {
+    DCHECK_EQ(layout, CHANNEL_LAYOUT_MONO);
+  }
+
+  return channel_count;
+}
+
+ChannelMixer::ChannelMixer(ChannelLayout input, ChannelLayout output)
+    : input_layout_(input),
+      output_layout_(output),
+      remapping_(false) {
+  // Stereo down mix should never be the output layout.
+  CHECK_NE(output_layout_, CHANNEL_LAYOUT_STEREO_DOWNMIX);
+

[Chris Rogers, 2012/10/19 20:48:17]

maybe we should at least DCHECK that input!=output.  Although technically this
class will handle this case, for efficiency don't we want to avoid using this
class in this case.  I'm not sure, WDYT?

[DaleCurtis, 2012/10/19 22:33:20]

Since these layouts might be chosen dynamically, i'd rather leave it up to the
caller.  Per Chromium style you're not supposed to DCHECK things you handle
anyways.

+  int input_channels = ValidateLayout(input_layout_);
+  int output_channels = ValidateLayout(output_layout_);
+
+  // Size out the initial matrix.
+  matrix_.reserve(output_channels);
+  for (int output_ch = 0; output_ch < output_channels; ++output_ch)
+    matrix_.push_back(std::vector<float>(input_channels, 0));
+
+  // Route matching channels and figure out which ones aren't accounted for.
+  for (Channels ch = LEFT; ch < CHANNELS_MAX;
+       ch = static_cast<Channels>(ch + 1)) {
+    int input_ch_index = ChannelOrder(input_layout_, ch);
+    int output_ch_index = ChannelOrder(output_layout_, ch);
+
+    if (input_ch_index < 0)
+      continue;
+
+    if (output_ch_index < 0) {
+      unaccounted_inputs_.push_back(ch);
+      continue;
+    }
+
+    DCHECK_LT(static_cast<size_t>(output_ch_index), matrix_.size());
+    DCHECK_LT(static_cast<size_t>(input_ch_index),
+              matrix_[output_ch_index].size());
+    matrix_[output_ch_index][input_ch_index] = 1;
+  }
+
+  // If all input channels are accounted for, there's nothing left to do.
+  if (unaccounted_inputs_.empty()) {
+    // Since all output channels map directly to inputs we can optimize.
+    remapping_ = true;
+    return;
+  }
+
+  // Mix front LR into center.
+  if (IsUnaccounted(LEFT)) {
+    // When down mixing to mono from stereo, we need to be careful of full scale
+    // stereo mixes.  Scaling by 1 / sqrt(2) here will likely lead to clipping
+    // so we use 1 / 2 instead.
+    float scale = (output == CHANNEL_LAYOUT_MONO && input_channels == 2) ?
+        0.5 : kDefaultScale;
+    Mix(LEFT, CENTER, scale);
+    Mix(RIGHT, CENTER, scale);
+  }
+
+  // Mix center into front LR.
+  if (IsUnaccounted(CENTER)) {
+    // When up mixing from mono, just do a copy to front LR.
+    float scale = (input == CHANNEL_LAYOUT_MONO) ? 1 : kDefaultScale;
+    MixWithoutAccounting(CENTER, LEFT, scale);
+    Mix(CENTER, RIGHT, scale);
+  }
+
+  // Mix back LR into: side LR || back center || front LR || front center.
+  if (IsUnaccounted(BACK_LEFT)) {
+    if (HasOutputChannel(SIDE_LEFT)) {
+      // If we have side LR, mix back LR into side LR, but instead if the input
+      // doesn't have side LR (but output does) copy back LR to side LR.
+      float scale = HasInputChannel(SIDE_LEFT) ? kDefaultScale : 1;
+      Mix(BACK_LEFT, SIDE_LEFT, scale);
+      Mix(BACK_RIGHT, SIDE_RIGHT, scale);
+    } else if (HasOutputChannel(BACK_CENTER)) {
+      // Mix back LR into back center.
+      Mix(BACK_LEFT, BACK_CENTER, kDefaultScale);
+      Mix(BACK_RIGHT, BACK_CENTER, kDefaultScale);
+    } else if (output > CHANNEL_LAYOUT_MONO) {
+      // Mix back LR into front LR.
+      Mix(BACK_LEFT, LEFT, kDefaultScale);
+      Mix(BACK_RIGHT, RIGHT, kDefaultScale);
+    } else {
+      // Mix back LR into front center.
+      Mix(BACK_LEFT, CENTER, kDefaultScale);
+      Mix(BACK_RIGHT, CENTER, kDefaultScale);
+    }
+  }
+
+  // Mix side LR into: back LR || back center || front LR || front center.
+  if (IsUnaccounted(SIDE_LEFT)) {
+    if (HasOutputChannel(BACK_LEFT)) {
+      // If we have back LR, mix side LR into back LR, but instead if the input
+      // doesn't have back LR (but output does) copy side LR to back LR.
+      float scale = HasInputChannel(BACK_LEFT) ? kDefaultScale : 1;
+      Mix(SIDE_LEFT, BACK_LEFT, scale);
+      Mix(SIDE_RIGHT, BACK_RIGHT, scale);
+    } else if (HasOutputChannel(BACK_CENTER)) {
+      // Mix side LR into back center.
+      Mix(SIDE_LEFT, BACK_CENTER, kDefaultScale);
+      Mix(SIDE_RIGHT, BACK_CENTER, kDefaultScale);
+    } else if (output > CHANNEL_LAYOUT_MONO) {
+      // Mix side LR into front LR.
+      Mix(SIDE_LEFT, LEFT, kDefaultScale);
+      Mix(SIDE_RIGHT, RIGHT, kDefaultScale);
+    } else {
+      // Mix side LR into front center.
+      Mix(SIDE_LEFT, CENTER, kDefaultScale);
+      Mix(SIDE_RIGHT, CENTER, kDefaultScale);
+    }
+  }
+
+  // Mix back center into: back LR || side LR || front LR || front center.
+  if (IsUnaccounted(BACK_CENTER)) {
+    if (HasOutputChannel(BACK_LEFT)) {
+      // Mix back center into back LR.
+      MixWithoutAccounting(BACK_CENTER, BACK_LEFT, kDefaultScale);
+      Mix(BACK_CENTER, BACK_RIGHT, kDefaultScale);
+    } else if (HasOutputChannel(SIDE_LEFT)) {
+      // Mix back center into side LR.
+      MixWithoutAccounting(BACK_CENTER, SIDE_LEFT, kDefaultScale);
+      Mix(BACK_CENTER, SIDE_RIGHT, kDefaultScale);
+    } else if (output > CHANNEL_LAYOUT_MONO) {
+      // Mix back center into front LR.
+      // TODO(dalecurtis): Not sure about these values?
+      MixWithoutAccounting(BACK_CENTER, LEFT, kDefaultScale * kDefaultScale);

[Chris Rogers, 2012/10/19 20:48:17]

why kDefaultScale*kDefaultScale ? -- I would just use kDefaultScale.

You can still leave the TODO comment

[DaleCurtis, 2012/10/19 22:33:20]

ffmpeg used that value, my assumption was that you don't want to scale the rear
channels equally into the fronts since they are further away. Done.

+      Mix(BACK_CENTER, RIGHT, kDefaultScale * kDefaultScale);
+    } else {
+      // Mix back center into front center.
+      // TODO(dalecurtis): Not sure about these values?
+      Mix(BACK_CENTER, CENTER, kDefaultScale * kDefaultScale);
+    }
+  }
+
+  // Mix LR of center into: front center || front LR.
+  if (IsUnaccounted(LEFT_OF_CENTER)) {
+    if (HasOutputChannel(CENTER)) {
+      // Mix LR of center into front center.
+      Mix(LEFT_OF_CENTER, CENTER, kDefaultScale);
+      Mix(RIGHT_OF_CENTER, CENTER, kDefaultScale);
+    } else {
+      // Mix LR of center into front LR.
+      Mix(LEFT_OF_CENTER, LEFT, kDefaultScale);
+      Mix(RIGHT_OF_CENTER, RIGHT, kDefaultScale);
+    }
+  }
+
+  // Mix LFE into: front LR || front center.
+  if (IsUnaccounted(LFE)) {
+    if (!HasOutputChannel(CENTER)) {
+      // Mix LFE into front LR.
+      MixWithoutAccounting(LFE, LEFT, kDefaultScale);
+      Mix(LFE, RIGHT, kDefaultScale);
+    } else {
+      // Mix LFE into front center.
+      Mix(LFE, CENTER, kDefaultScale);
+    }
+  }
+
+  // All channels should now be accounted for.
+  DCHECK(unaccounted_inputs_.empty());
+
+  // See if the output |matrix_| is simply a remapping matrix.  If each input
+  // channel maps to a single output channel we can simply remap.  Doing this
+  // programmatically is less fragile than logic checks on channel mappings.
+  for (int output_ch = 0; output_ch < output_channels; ++output_ch) {
+    int input_mappings = 0;
+    for (int input_ch = 0; input_ch < input_channels; ++input_ch) {
+      // We can only remap if each row contains a single scale of 1.  I.e., each
+      // output channel is mapped from a single unscaled input channel.
+      if (matrix_[output_ch][input_ch] != 1 || ++input_mappings > 1)
+        return;
+    }
+  }
+
+  // If we've gotten here, |matrix_| is simply a remapping.
+  remapping_ = true;
+}
+
+ChannelMixer::~ChannelMixer() {}
+
+void ChannelMixer::Transform(const AudioBus* input, AudioBus* output) {
+  CHECK_EQ(matrix_.size(), static_cast<size_t>(output->channels()));
+  CHECK_EQ(matrix_[0].size(), static_cast<size_t>(input->channels()));
+  CHECK_EQ(input->frames(), output->frames());
+
+  // Zero initialize |output| so we're accumulating from zero.
+  output->Zero();
+
+  // If we're just remapping we can simply copy the correct input to output.
+  if (remapping_) {
+    for (int output_ch = 0; output_ch < output->channels(); ++output_ch) {
+      for (int input_ch = 0; input_ch < input->channels(); ++input_ch) {
+        float scale = matrix_[output_ch][input_ch];
+        if (scale > 0) {
+          DCHECK_EQ(scale, 1.0f);
+          memcpy(output->channel(output_ch), input->channel(input_ch),
+                 sizeof(*output->channel(output_ch)) * output->frames());
+          break;
+        }
+      }
+    }
+    return;
+  }
+
+  for (int output_ch = 0; output_ch < output->channels(); ++output_ch) {
+    for (int input_ch = 0; input_ch < input->channels(); ++input_ch) {
+      float scale = matrix_[output_ch][input_ch];
+      // Scale should always be positive.  Don't bother scaling by zero.
+      DCHECK_GE(scale, 0);
+      if (scale > 0) {
+        vector_math::FMAC(input->channel(input_ch), scale, output->frames(),
+                          output->channel(output_ch));
+      }
+    }
+  }
+}
+
+void ChannelMixer::AccountFor(Channels ch) {
+  unaccounted_inputs_.erase(std::find(
+      unaccounted_inputs_.begin(), unaccounted_inputs_.end(), ch));
+}
+
+bool ChannelMixer::IsUnaccounted(Channels ch) {
+  return std::find(unaccounted_inputs_.begin(), unaccounted_inputs_.end(),
+                   ch) != unaccounted_inputs_.end();
+}
+
+bool ChannelMixer::HasInputChannel(Channels ch) {
+  return ChannelOrder(input_layout_, ch) >= 0;
+}
+
+bool ChannelMixer::HasOutputChannel(Channels ch) {
+  return ChannelOrder(output_layout_, ch) >= 0;
+}
+
+void ChannelMixer::Mix(Channels input_ch, Channels output_ch, float scale) {
+  MixWithoutAccounting(input_ch, output_ch, scale);
+  AccountFor(input_ch);
+}
+
+void ChannelMixer::MixWithoutAccounting(Channels input_ch, Channels output_ch,
+                                        float scale) {
+  int input_ch_index = ChannelOrder(input_layout_, input_ch);
+  int output_ch_index = ChannelOrder(output_layout_, output_ch);
+
+  DCHECK(IsUnaccounted(input_ch));
+  DCHECK_GE(input_ch_index, 0);
+  DCHECK_GE(output_ch_index, 0);
+
+  matrix_[output_ch_index][input_ch_index] += scale;

[Chris Rogers, 2012/10/19 20:48:17]

I'm confused why we're accumulating |scale| here.  Shouldn't we DCHECK that the
current location in the matrix is 0 and simply set it here.  Maybe I'm missing
something.

[DaleCurtis, 2012/10/19 22:33:20]

Ah, yes, you're correct. This is a carryover from earlier algorithms I was
experimenting with.

+}
+
+}  // namespace media