Add AudioListener (audio equivalent to VideoListener)

Issue: #3994

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=204722997

RELEASENOTES.md

@@ -2,6 +2,8 @@
 
 ### dev-v2 (not yet released) ###
 
+* Add `AudioListener` for listening to changes in audio configuration during
+  playback ([#3994](https://github.com/google/ExoPlayer/issues/3994)).
 * MPEG-PS: Support reading duration from MPEG-PS Streams
   ([#4476](https://github.com/google/ExoPlayer/issues/4476)).
 * MediaSession extension:

library/core/src/main/java/com/google/android/exoplayer2/Player.java

@@ -23,6 +23,7 @@ import android.view.SurfaceHolder;
 import android.view.SurfaceView;
 import android.view.TextureView;
 import com.google.android.exoplayer2.audio.AudioAttributes;
+import com.google.android.exoplayer2.audio.AudioListener;
 import com.google.android.exoplayer2.source.TrackGroupArray;
 import com.google.android.exoplayer2.text.TextOutput;
 import com.google.android.exoplayer2.trackselection.TrackSelectionArray;
@@ -55,6 +56,20 @@ public interface Player {
   /** The audio component of a {@link Player}. */
   interface AudioComponent {
 
+    /**
+     * Adds a listener to receive audio events.
+     *
+     * @param listener The listener to register.
+     */
+    void addAudioListener(AudioListener listener);
+
+    /**
+     * Removes a listener of audio events.
+     *
+     * @param listener The listener to unregister.
+     */
+    void removeAudioListener(AudioListener listener);
+
     /**
      * Sets the attributes for audio playback, used by the underlying audio track. If not set, the
      * default audio attributes will be used. They are suitable for general media playback.

library/core/src/main/java/com/google/android/exoplayer2/SimpleExoPlayer.java

@@ -31,6 +31,7 @@ import android.view.TextureView;
 import com.google.android.exoplayer2.analytics.AnalyticsCollector;
 import com.google.android.exoplayer2.analytics.AnalyticsListener;
 import com.google.android.exoplayer2.audio.AudioAttributes;
+import com.google.android.exoplayer2.audio.AudioListener;
 import com.google.android.exoplayer2.audio.AudioRendererEventListener;
 import com.google.android.exoplayer2.decoder.DecoderCounters;
 import com.google.android.exoplayer2.drm.DefaultDrmSessionManager;
@@ -73,6 +74,7 @@ public class SimpleExoPlayer
   private final ComponentListener componentListener;
   private final CopyOnWriteArraySet<com.google.android.exoplayer2.video.VideoListener>
       videoListeners;
+  private final CopyOnWriteArraySet<AudioListener> audioListeners;
   private final CopyOnWriteArraySet<TextOutput> textOutputs;
   private final CopyOnWriteArraySet<MetadataOutput> metadataOutputs;
   private final CopyOnWriteArraySet<VideoRendererEventListener> videoDebugListeners;
@@ -185,6 +187,7 @@ public class SimpleExoPlayer
       Looper looper) {
     componentListener = new ComponentListener();
     videoListeners = new CopyOnWriteArraySet<>();
+    audioListeners = new CopyOnWriteArraySet<>();
     textOutputs = new CopyOnWriteArraySet<>();
     metadataOutputs = new CopyOnWriteArraySet<>();
     videoDebugListeners = new CopyOnWriteArraySet<>();
@@ -213,6 +216,7 @@ public class SimpleExoPlayer
     videoDebugListeners.add(analyticsCollector);
     videoListeners.add(analyticsCollector);
     audioDebugListeners.add(analyticsCollector);
+    audioListeners.add(analyticsCollector);
     addMetadataOutput(analyticsCollector);
     if (drmSessionManager instanceof DefaultDrmSessionManager) {
       ((DefaultDrmSessionManager) drmSessionManager).addListener(eventHandler, analyticsCollector);
@@ -350,8 +354,21 @@ public class SimpleExoPlayer
     }
   }
 
+  @Override
+  public void addAudioListener(AudioListener listener) {
+    audioListeners.add(listener);
+  }
+
+  @Override
+  public void removeAudioListener(AudioListener listener) {
+    audioListeners.remove(listener);
+  }
+
   @Override
   public void setAudioAttributes(AudioAttributes audioAttributes) {
+    if (Util.areEqual(this.audioAttributes, audioAttributes)) {
+      return;
+    }
     this.audioAttributes = audioAttributes;
     for (Renderer renderer : renderers) {
       if (renderer.getTrackType() == C.TRACK_TYPE_AUDIO) {
@@ -362,6 +379,9 @@ public class SimpleExoPlayer
             .send();
       }
     }
+    for (AudioListener audioListener : audioListeners) {
+      audioListener.onAudioAttributesChanged(audioAttributes);
+    }
   }
 
   @Override
@@ -376,12 +396,19 @@ public class SimpleExoPlayer
 
   @Override
   public void setVolume(float audioVolume) {
+    audioVolume = Util.constrainValue(audioVolume, /* min= */ 0, /* max= */ 1);
+    if (this.audioVolume == audioVolume) {
+      return;
+    }
     this.audioVolume = audioVolume;
     for (Renderer renderer : renderers) {
       if (renderer.getTrackType() == C.TRACK_TYPE_AUDIO) {
         player.createMessage(renderer).setType(C.MSG_SET_VOLUME).setPayload(audioVolume).send();
       }
     }
+    for (AudioListener audioListener : audioListeners) {
+      audioListener.onVolumeChanged(audioVolume);
+    }
   }
 
   @Override
@@ -1075,8 +1102,8 @@ public class SimpleExoPlayer
     public void onVideoSizeChanged(int width, int height, int unappliedRotationDegrees,
         float pixelWidthHeightRatio) {
       for (com.google.android.exoplayer2.video.VideoListener videoListener : videoListeners) {
-        // Prevent duplicate notification if a listener is both a VideoRendererDebugListener and
-        // VideoListener as they have the same method signature.
+        // Prevent duplicate notification if a listener is both a VideoRendererEventListener and
+        // a VideoListener, as they have the same method signature.
         if (!videoDebugListeners.contains(videoListener)) {
           videoListener.onVideoSizeChanged(
               width, height, unappliedRotationDegrees, pixelWidthHeightRatio);
@@ -1121,7 +1148,17 @@ public class SimpleExoPlayer
 
     @Override
     public void onAudioSessionId(int sessionId) {
+      if (audioSessionId == sessionId) {
+        return;
+      }
       audioSessionId = sessionId;
+      for (AudioListener audioListener : audioListeners) {
+        // Prevent duplicate notification if a listener is both a AudioRendererEventListener and
+        // a AudioListener, as they have the same method signature.
+        if (!audioDebugListeners.contains(audioListener)) {
+          audioListener.onAudioSessionId(sessionId);
+        }
+      }
       for (AudioRendererEventListener audioDebugListener : audioDebugListeners) {
         audioDebugListener.onAudioSessionId(sessionId);
       }

library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsCollector.java

@@ -26,6 +26,8 @@ import com.google.android.exoplayer2.Timeline;
 import com.google.android.exoplayer2.Timeline.Period;
 import com.google.android.exoplayer2.Timeline.Window;
 import com.google.android.exoplayer2.analytics.AnalyticsListener.EventTime;
+import com.google.android.exoplayer2.audio.AudioAttributes;
+import com.google.android.exoplayer2.audio.AudioListener;
 import com.google.android.exoplayer2.audio.AudioRendererEventListener;
 import com.google.android.exoplayer2.decoder.DecoderCounters;
 import com.google.android.exoplayer2.drm.DefaultDrmSessionEventListener;
@@ -60,7 +62,8 @@ public class AnalyticsCollector
         MediaSourceEventListener,
         BandwidthMeter.EventListener,
         DefaultDrmSessionEventListener,
-        VideoListener {
+        VideoListener,
+        AudioListener {
 
   /** Factory for an analytics collector. */
   public static class Factory {
@@ -181,14 +184,6 @@ public class AnalyticsCollector
     }
   }
 
-  @Override
-  public final void onAudioSessionId(int audioSessionId) {
-    EventTime eventTime = generateReadingMediaPeriodEventTime();
-    for (AnalyticsListener listener : listeners) {
-      listener.onAudioSessionId(eventTime, audioSessionId);
-    }
-  }
-
   @Override
   public final void onAudioDecoderInitialized(
       String decoderName, long initializedTimestampMs, long initializationDurationMs) {
@@ -226,6 +221,32 @@ public class AnalyticsCollector
     }
   }
 
+  // AudioListener implementation.
+
+  @Override
+  public final void onAudioSessionId(int audioSessionId) {
+    EventTime eventTime = generateReadingMediaPeriodEventTime();
+    for (AnalyticsListener listener : listeners) {
+      listener.onAudioSessionId(eventTime, audioSessionId);
+    }
+  }
+
+  @Override
+  public void onAudioAttributesChanged(AudioAttributes audioAttributes) {
+    EventTime eventTime = generateReadingMediaPeriodEventTime();
+    for (AnalyticsListener listener : listeners) {
+      listener.onAudioAttributesChanged(eventTime, audioAttributes);
+    }
+  }
+
+  @Override
+  public void onVolumeChanged(float audioVolume) {
+    EventTime eventTime = generateReadingMediaPeriodEventTime();
+    for (AnalyticsListener listener : listeners) {
+      listener.onVolumeChanged(eventTime, audioVolume);
+    }
+  }
+
   // VideoRendererEventListener implementation.
 
   @Override
@@ -263,16 +284,6 @@ public class AnalyticsCollector
     }
   }
 
-  @Override
-  public final void onVideoSizeChanged(
-      int width, int height, int unappliedRotationDegrees, float pixelWidthHeightRatio) {
-    EventTime eventTime = generateReadingMediaPeriodEventTime();
-    for (AnalyticsListener listener : listeners) {
-      listener.onVideoSizeChanged(
-          eventTime, width, height, unappliedRotationDegrees, pixelWidthHeightRatio);
-    }
-  }
-
   @Override
   public final void onVideoDisabled(DecoderCounters counters) {
     // The renderers are disabled after we changed the playing media period on the playback thread
@@ -294,8 +305,13 @@ public class AnalyticsCollector
   // VideoListener implementation.
 
   @Override
-  public final void onRenderedFirstFrame() {
-    // Do nothing. Already reported in VideoRendererEventListener.onRenderedFirstFrame.
+  public final void onVideoSizeChanged(
+      int width, int height, int unappliedRotationDegrees, float pixelWidthHeightRatio) {
+    EventTime eventTime = generateReadingMediaPeriodEventTime();
+    for (AnalyticsListener listener : listeners) {
+      listener.onVideoSizeChanged(
+          eventTime, width, height, unappliedRotationDegrees, pixelWidthHeightRatio);
+    }
   }
 
   @Override
@@ -306,6 +322,11 @@ public class AnalyticsCollector
     }
   }
 
+  @Override
+  public final void onRenderedFirstFrame() {
+    // Do nothing. Already reported in VideoRendererEventListener.onRenderedFirstFrame.
+  }
+
   // MediaSourceEventListener implementation.
 
   @Override

library/core/src/main/java/com/google/android/exoplayer2/analytics/AnalyticsListener.java

@@ -25,6 +25,7 @@ import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Player.DiscontinuityReason;
 import com.google.android.exoplayer2.Player.TimelineChangeReason;
 import com.google.android.exoplayer2.Timeline;
+import com.google.android.exoplayer2.audio.AudioAttributes;
 import com.google.android.exoplayer2.audio.AudioSink;
 import com.google.android.exoplayer2.decoder.DecoderCounters;
 import com.google.android.exoplayer2.metadata.Metadata;
@@ -379,6 +380,22 @@ public interface AnalyticsListener {
    */
   default void onAudioSessionId(EventTime eventTime, int audioSessionId) {}
 
+  /**
+   * Called when the audio attributes change.
+   *
+   * @param eventTime The event time.
+   * @param audioAttributes The audio attributes.
+   */
+  default void onAudioAttributesChanged(EventTime eventTime, AudioAttributes audioAttributes) {}
+
+  /**
+   * Called when the volume changes.
+   *
+   * @param eventTime The event time.
+   * @param volume The new volume, with 0 being silence and 1 being unity gain.
+   */
+  default void onVolumeChanged(EventTime eventTime, float volume) {}
+
   /**
    * Called when an audio underrun occurred.
    *

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2018 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.android.exoplayer2.audio;
+
+/** A listener for changes in audio configuration. */
+public interface AudioListener {
+
+  /**
+   * Called when the audio session is set.
+   *
+   * @param audioSessionId The audio session id.
+   */
+  default void onAudioSessionId(int audioSessionId) {}
+
+  /**
+   * Called when the audio attributes change.
+   *
+   * @param audioAttributes The audio attributes.
+   */
+  default void onAudioAttributesChanged(AudioAttributes audioAttributes) {}
+
+  /**
+   * Called when the volume changes.
+   *
+   * @param volume The new volume, with 0 being silence and 1 being unity gain.
+   */
+  default void onVolumeChanged(float volume) {}
+}

library/core/src/main/java/com/google/android/exoplayer2/video/VideoListener.java

@@ -34,8 +34,8 @@ public interface VideoListener {
    *     square pixels this will be equal to 1.0. Different values are indicative of anamorphic
    *     content.
    */
-  void onVideoSizeChanged(
-      int width, int height, int unappliedRotationDegrees, float pixelWidthHeightRatio);
+  default void onVideoSizeChanged(
+      int width, int height, int unappliedRotationDegrees, float pixelWidthHeightRatio) {}
 
   /**
    * Called each time there's a change in the size of the surface onto which the video is being
@@ -54,5 +54,5 @@ public interface VideoListener {
    * Called when a frame is rendered for the first time since setting the surface, and when a frame
    * is rendered for the first time since a video track was selected.
    */
-  void onRenderedFirstFrame();
+  default void onRenderedFirstFrame() {}
 }

library/core/src/test/java/com/google/android/exoplayer2/analytics/AnalyticsCollectorTest.java

@@ -822,7 +822,7 @@ public final class AnalyticsCollectorTest {
     @Override
     protected void onBufferRead() {
       if (!notifiedAudioSessionId) {
-        eventDispatcher.audioSessionId(/* audioSessionId= */ 0);
+        eventDispatcher.audioSessionId(/* audioSessionId= */ 1);
         notifiedAudioSessionId = true;
       }
     }