Map VORBIS channel layout to Android layout

Both the extension OPUS decoder and the OMX/C2 MediaCodec
implementations for OPUS and VORBIS decode into the channel
layout defined by VORBIS. See
https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-140001.2.3

While this is technically correct for a stand-alone OPUS or VORBIS
decoder, it doesn't match the channel layout expected by Android.
See https://developer.android.com/reference/android/media/AudioFormat#channelMask

The fix is to apply the channel mapping after decoding if needed.
Also add e2e tests with audio dumps for the extension renderer,
including a new 5.1 channel test file.

Issue: #8396

#minor-release

PiperOrigin-RevId: 588004832

extensions/opus/build.gradle

@@ -33,6 +33,7 @@ dependencies {
     compileOnly 'org.jetbrains.kotlin:kotlin-annotations-jvm:' + kotlinAnnotationsVersion
     testImplementation project(modulePrefix + 'testutils')
     testImplementation 'org.robolectric:robolectric:' + robolectricVersion
+    androidTestImplementation project(modulePrefix + 'testutils')
     androidTestImplementation 'androidx.test:runner:' + androidxTestRunnerVersion
     androidTestImplementation 'androidx.test.ext:junit:' + androidxTestJUnitVersion
 }

extensions/opus/src/androidTest/java/com/google/android/exoplayer2/ext/opus/OpusPlaybackTest.java

@@ -15,7 +15,7 @@
  */
 package com.google.android.exoplayer2.ext.opus;
 
-import static org.junit.Assert.fail;
+import static com.google.common.truth.Truth.assertWithMessage;
 
 import android.content.Context;
 import android.net.Uri;
@@ -29,9 +29,13 @@
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.RenderersFactory;
+import com.google.android.exoplayer2.audio.AudioSink;
+import com.google.android.exoplayer2.audio.DefaultAudioSink;
 import com.google.android.exoplayer2.extractor.mkv.MatroskaExtractor;
 import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.source.ProgressiveMediaSource;
+import com.google.android.exoplayer2.testutil.CapturingAudioSink;
+import com.google.android.exoplayer2.testutil.DumpFileAsserts;
 import com.google.android.exoplayer2.upstream.DefaultDataSource;
 import org.junit.Before;
 import org.junit.Test;
@@ -41,49 +45,69 @@
 @RunWith(AndroidJUnit4.class)
 public class OpusPlaybackTest {
 
-  private static final String BEAR_OPUS_URI = "asset:///media/mka/bear-opus.mka";
-  private static final String BEAR_OPUS_NEGATIVE_GAIN_URI =
-      "asset:///media/mka/bear-opus-negative-gain.mka";
+  private static final String BEAR_OPUS = "mka/bear-opus.mka";
+  private static final String BEAR_OPUS_NEGATIVE_GAIN = "mka/bear-opus-negative-gain.mka";
+  private static final String OPUS_5POINT1 = "mka/opus-5.1.mka";
 
   @Before
   public void setUp() {
-    if (!OpusLibrary.isAvailable()) {
-      fail("Opus library not available.");
-    }
+    assertWithMessage("Opus library not available").that(OpusLibrary.isAvailable()).isTrue();
+    assertWithMessage("Dump files were generated for x86_64")
+        .that(System.getProperty("os.arch"))
+        .isEqualTo("x86_64");
+  }
+
+  @Test
+  public void playBasicOpus() throws Exception {
+    playUri(BEAR_OPUS);
   }
 
   @Test
-  public void basicPlayback() throws Exception {
-    playUri(BEAR_OPUS_URI);
+  public void playWithNegativeGain() throws Exception {
+    playUri(BEAR_OPUS_NEGATIVE_GAIN);
   }
 
   @Test
-  public void basicPlaybackNegativeGain() throws Exception {
-    playUri(BEAR_OPUS_NEGATIVE_GAIN_URI);
+  public void play5Point1() throws Exception {
+    playUri(OPUS_5POINT1);
   }
 
-  private void playUri(String uri) throws Exception {
+  private void playUri(String fileName) throws Exception {
+    CapturingAudioSink audioSink =
+        new CapturingAudioSink(
+            new DefaultAudioSink.Builder(ApplicationProvider.getApplicationContext()).build());
+
     TestPlaybackRunnable testPlaybackRunnable =
-        new TestPlaybackRunnable(Uri.parse(uri), ApplicationProvider.getApplicationContext());
+        new TestPlaybackRunnable(
+            Uri.parse("asset:///media/" + fileName),
+            ApplicationProvider.getApplicationContext(),
+            audioSink);
     Thread thread = new Thread(testPlaybackRunnable);
     thread.start();
     thread.join();
+
     if (testPlaybackRunnable.playbackException != null) {
       throw testPlaybackRunnable.playbackException;
     }
+    DumpFileAsserts.assertOutput(
+        ApplicationProvider.getApplicationContext(),
+        audioSink,
+        "audiosinkdumps/" + fileName + ".audiosink.dump");
   }
 
   private static class TestPlaybackRunnable implements Player.Listener, Runnable {
 
     private final Context context;
     private final Uri uri;
+    private final AudioSink audioSink;
 
     @Nullable private ExoPlayer player;
     @Nullable private PlaybackException playbackException;
 
-    public TestPlaybackRunnable(Uri uri, Context context) {
+    public TestPlaybackRunnable(Uri uri, Context context, AudioSink audioSink) {
       this.uri = uri;
       this.context = context;
+      this.audioSink = audioSink;
     }
 
     @Override
@@ -95,7 +119,9 @@ public void run() {
               audioRendererEventListener,
               textRendererOutput,
               metadataRendererOutput) ->
-              new Renderer[] {new LibopusAudioRenderer(eventHandler, audioRendererEventListener)};
+              new Renderer[] {
+                new LibopusAudioRenderer(eventHandler, audioRendererEventListener, audioSink)
+              };
       player = new ExoPlayer.Builder(context, renderersFactory).build();
       player.addListener(this);
       MediaSource mediaSource =

extensions/opus/src/main/java/com/google/android/exoplayer2/ext/opus/LibopusAudioRenderer.java

@@ -25,6 +25,7 @@
 import com.google.android.exoplayer2.audio.AudioSink.SinkFormatSupport;
 import com.google.android.exoplayer2.audio.DecoderAudioRenderer;
 import com.google.android.exoplayer2.decoder.CryptoConfig;
+import com.google.android.exoplayer2.extractor.VorbisUtil;
 import com.google.android.exoplayer2.util.MimeTypes;
 import com.google.android.exoplayer2.util.TraceUtil;
 import com.google.android.exoplayer2.util.Util;
@@ -138,6 +139,12 @@ protected final Format getOutputFormat(OpusDecoder decoder) {
     return Util.getPcmFormat(pcmEncoding, decoder.channelCount, OpusDecoder.SAMPLE_RATE);
   }
 
+  @Nullable
+  @Override
+  protected int[] getChannelMapping(OpusDecoder decoder) {
+    return VorbisUtil.getVorbisToAndroidChannelLayoutMapping(decoder.channelCount);
+  }
+
   /**
    * Returns true if support for padding removal from the end of decoder output buffer should be
    * enabled.

library/core/src/main/java/com/google/android/exoplayer2/audio/DecoderAudioRenderer.java

@@ -374,6 +374,18 @@ protected abstract T createDecoder(Format format, @Nullable CryptoConfig cryptoC
   @ForOverride
   protected abstract Format getOutputFormat(T decoder);
 
+  /**
+   * Returns the channel layout mapping that should be applied when sending this data to the output,
+   * or null to not change the channel layout.
+   *
+   * @param decoder The decoder.
+   */
+  @ForOverride
+  @Nullable
+  protected int[] getChannelMapping(T decoder) {
+    return null;
+  }
+
   /**
    * Evaluates whether the existing decoder can be reused for a new {@link Format}.
    *
@@ -444,7 +456,7 @@ private boolean drainOutputBuffer()
               .setSelectionFlags(inputFormat.selectionFlags)
               .setRoleFlags(inputFormat.roleFlags)
               .build();
-      audioSink.configure(outputFormat, /* specifiedBufferSize= */ 0, /* outputChannels= */ null);
+      audioSink.configure(outputFormat, /* specifiedBufferSize= */ 0, getChannelMapping(decoder));
       audioTrackNeedsConfigure = false;
     }
 

library/core/src/main/java/com/google/android/exoplayer2/audio/MediaCodecAudioRenderer.java

@@ -48,6 +48,7 @@
 import com.google.android.exoplayer2.decoder.DecoderInputBuffer;
 import com.google.android.exoplayer2.decoder.DecoderReuseEvaluation;
 import com.google.android.exoplayer2.decoder.DecoderReuseEvaluation.DecoderDiscardReasons;
+import com.google.android.exoplayer2.extractor.VorbisUtil;
 import com.google.android.exoplayer2.mediacodec.MediaCodecAdapter;
 import com.google.android.exoplayer2.mediacodec.MediaCodecInfo;
 import com.google.android.exoplayer2.mediacodec.MediaCodecRenderer;
@@ -109,6 +110,7 @@ public class MediaCodecAudioRenderer extends MediaCodecRenderer implements Media
 
   private int codecMaxInputSize;
   private boolean codecNeedsDiscardChannelsWorkaround;
+  private boolean codecNeedsVorbisToAndroidChannelMappingWorkaround;
   @Nullable private Format inputFormat;
 
   /** Codec used for DRM decryption only in passthrough and offload. */
@@ -436,6 +438,8 @@ protected MediaCodecAdapter.Configuration getMediaCodecConfiguration(
       float codecOperatingRate) {
     codecMaxInputSize = getCodecMaxInputSize(codecInfo, format, getStreamFormats());
     codecNeedsDiscardChannelsWorkaround = codecNeedsDiscardChannelsWorkaround(codecInfo.name);
+    codecNeedsVorbisToAndroidChannelMappingWorkaround =
+        codecNeedsVorbisToAndroidChannelMappingWorkaround(codecInfo.name);
     MediaFormat mediaFormat =
         getMediaFormat(format, codecInfo.codecMimeType, codecMaxInputSize, codecOperatingRate);
     // Store the input MIME type if we're only using the codec for decryption.
@@ -568,6 +572,9 @@ protected void onOutputFormatChanged(Format format, @Nullable MediaFormat mediaF
         for (int i = 0; i < format.channelCount; i++) {
           channelMap[i] = i;
         }
+      } else if (codecNeedsVorbisToAndroidChannelMappingWorkaround) {
+        channelMap =
+            VorbisUtil.getVorbisToAndroidChannelLayoutMapping(audioSinkInputFormat.channelCount);
       }
     }
     try {
@@ -973,6 +980,19 @@ private static boolean codecNeedsDiscardChannelsWorkaround(String codecName) {
             || Util.DEVICE.startsWith("heroqlte"));
   }
 
+  /**
+   * Returns whether the decoder is known to output PCM samples in VORBIS order, which does not
+   * match the channel layout required by AudioTrack.
+   *
+   * <p>See https://github.com/google/ExoPlayer/issues/8396#issuecomment-1833867901.
+   */
+  private static boolean codecNeedsVorbisToAndroidChannelMappingWorkaround(String codecName) {
+    return codecName.equals("OMX.google.opus.decoder")
+        || codecName.equals("c2.android.opus.decoder")
+        || codecName.equals("OMX.google.vorbis.decoder")
+        || codecName.equals("c2.android.vorbis.decoder");
+  }
+
   private final class AudioSinkListener implements AudioSink.Listener {
 
     @Override

library/extractor/src/main/java/com/google/android/exoplayer2/extractor/VorbisUtil.java

@@ -148,6 +148,31 @@ public Mode(boolean blockFlag, int windowType, int transformType, int mapping) {
 
   private static final String TAG = "VorbisUtil";
 
+  /**
+   * Returns the mapping from VORBIS channel layout to the channel layout expected by Android, or
+   * null if the mapping is unchanged.
+   *
+   * <p>See https://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#x1-140001.2.3 and
+   * https://developer.android.com/reference/android/media/AudioFormat#channelMask.
+   */
+  @Nullable
+  public static int[] getVorbisToAndroidChannelLayoutMapping(int channelCount) {
+    switch (channelCount) {
+      case 3:
+        return new int[] {0, 2, 1};
+      case 5:
+        return new int[] {0, 2, 1, 3, 4};
+      case 6:
+        return new int[] {0, 2, 1, 5, 3, 4};
+      case 7:
+        return new int[] {0, 2, 1, 6, 5, 3, 4};
+      case 8:
+        return new int[] {0, 2, 1, 7, 5, 6, 3, 4};
+      default:
+        return null;
+    }
+  }
+
   /**
    * Returns ilog(x), which is the index of the highest set bit in {@code x}.
    *