Deprecate component listener in favor of player

All `add*Listener` and `add*Output` methods are
deprecated in favor of `addListener`.

As for the class themselves `VideoListener` and
`AudioListener` are not used internaly by ExoPlayer,
`VideoRendererEventListener`
and `AudioRendererEventListener` are use in their
place.
As a result `VideoListener` and `AudioListener`
can be deprecated in favor `Listener`.

On the other hand `TextOutput` and `MedataOutput`
are used both in the player interface and internally in
renderers.
This means that those class can't be deprecated.
There usage in the public interface are indirectly
deprecated as their is no way to use them without
using the deprecated `add*Output`.
Thus it's not an issue that the class themselves are
not deprecated.

#minor-release

PiperOrigin-RevId: 371318268

RELEASENOTES.md

@@ -30,7 +30,7 @@
         `ExoPlayer`.
         `ExoPlayer`.
     *   Add `getMediaMetadata` to `Player` interface.
     *   Add `getMediaMetadata` to `Player` interface.
     *   Add a `Listener` interface to receive all player events in a single
     *   Add a `Listener` interface to receive all player events in a single
-        object.
+        object. Component Listeners have been deprecated in its favor.
     *   `Player.setPlaybackParameters` no longer accepts null, use
     *   `Player.setPlaybackParameters` no longer accepts null, use
         `PlaybackParameters.DEFAULT` instead.
         `PlaybackParameters.DEFAULT` instead.
     *   Use an empty string instead of the URI if the media ID is not explicitly
     *   Use an empty string instead of the URI if the media ID is not explicitly

demos/main/src/main/java/com/google/android/exoplayer2/demo/PlayerActivity.java

@@ -77,7 +77,7 @@ public class PlayerActivity extends AppCompatActivity
   protected StyledPlayerView playerView;
   protected StyledPlayerView playerView;
   protected LinearLayout debugRootView;
   protected LinearLayout debugRootView;
   protected TextView debugTextView;
   protected TextView debugTextView;
-  protected SimpleExoPlayer player;
+  protected @Nullable SimpleExoPlayer player;
 
 
   private boolean isShowingTrackSelectionDialog;
   private boolean isShowingTrackSelectionDialog;
   private Button selectTracksButton;
   private Button selectTracksButton;

docs/listening-to-player-events.md

@@ -177,23 +177,14 @@ generic `onEvents` callback, for example to record media item change reasons
 with `onMediaItemTransition`, but only act once all state changes can be used
 with `onMediaItemTransition`, but only act once all state changes can be used
 together in `onEvents`.
 together in `onEvents`.
 
 
-## Additional SimpleExoPlayer listeners ##
+## SimpleExoPlayer listeners ##
 
 
-When using `SimpleExoPlayer`, additional listeners can be registered with the
+When using `SimpleExoPlayer`, an additional listener can be registered with the
 player.
 player.
 
 
 * `addAnalyticsListener`: Listen to detailed events that may be useful for
 * `addAnalyticsListener`: Listen to detailed events that may be useful for
   analytics and logging purposes. Please refer to the [analytics page][] for
   analytics and logging purposes. Please refer to the [analytics page][] for
   more details.
   more details.
-* `addTextOutput`: Listen to changes in the subtitle or caption cues.
-* `addMetadataOutput`: Listen to timed metadata events, such as timed ID3 and
-  EMSG data.
-* `addVideoListener`: Listen to events related to video rendering that may be
-  useful for adjusting the UI (e.g., the aspect ratio of the `Surface` onto
-  which video is being rendered).
-* `addAudioListener`: Listen to events related to audio, such as when an audio
-  session ID changes, and when the player volume is changed.
-* `addDeviceListener`: Listen to events related to the state of the device.
 
 
 ExoPlayer's UI components, such as `StyledPlayerView`, will register themselves
 ExoPlayer's UI components, such as `StyledPlayerView`, will register themselves
 as listeners to events that they are interested in. Hence manual registration
 as listeners to events that they are interested in. Hence manual registration

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

@@ -15,7 +15,14 @@
  */
  */
 package com.google.android.exoplayer2.audio;
 package com.google.android.exoplayer2.audio;
 
 
-/** A listener for changes in audio configuration. */
+import com.google.android.exoplayer2.Player;
+
+/**
+ * A listener for changes in audio configuration.
+ *
+ * @deprecated Use {@link Player.Listener}.
+ */
+@Deprecated
 public interface AudioListener {
 public interface AudioListener {
 
 
   /**
   /**

library/common/src/main/java/com/google/android/exoplayer2/device/DeviceListener.java

@@ -15,7 +15,14 @@
  */
  */
 package com.google.android.exoplayer2.device;
 package com.google.android.exoplayer2.device;
 
 
-/** A listener for changes of {@link DeviceInfo} or device volume. */
+import com.google.android.exoplayer2.Player;
+
+/**
+ * A listener for changes of {@link DeviceInfo} or device volume.
+ *
+ * @deprecated Use {@link Player.Listener}.
+ */
+@Deprecated
 public interface DeviceListener {
 public interface DeviceListener {
 
 
   /** Called when the device information changes. */
   /** Called when the device information changes. */

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

@@ -16,8 +16,14 @@
 package com.google.android.exoplayer2.video;
 package com.google.android.exoplayer2.video;
 
 
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.C;
+import com.google.android.exoplayer2.Player;
 
 
-/** A listener for metadata corresponding to video being rendered. */
+/**
+ * A listener for metadata corresponding to video being rendered.
+ *
+ * @deprecated Use {@link Player.Listener}.
+ */
+@Deprecated
 public interface VideoListener {
 public interface VideoListener {
 
 
   /**
   /**

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

@@ -149,14 +149,18 @@ public interface ExoPlayer extends Player {
      * Adds a listener to receive audio events.
      * Adds a listener to receive audio events.
      *
      *
      * @param listener The listener to register.
      * @param listener The listener to register.
+     * @deprecated Use {@link #addListener(Listener)}.
      */
      */
+    @Deprecated
     void addAudioListener(AudioListener listener);
     void addAudioListener(AudioListener listener);
 
 
     /**
     /**
      * Removes a listener of audio events.
      * Removes a listener of audio events.
      *
      *
      * @param listener The listener to unregister.
      * @param listener The listener to unregister.
+     * @deprecated Use {@link #removeListener(Listener)}.
      */
      */
+    @Deprecated
     void removeAudioListener(AudioListener listener);
     void removeAudioListener(AudioListener listener);
 
 
     /**
     /**
@@ -249,14 +253,18 @@ public interface ExoPlayer extends Player {
      * Adds a listener to receive video events.
      * Adds a listener to receive video events.
      *
      *
      * @param listener The listener to register.
      * @param listener The listener to register.
+     * @deprecated Use {@link #addListener(Listener)}.
      */
      */
+    @Deprecated
     void addVideoListener(VideoListener listener);
     void addVideoListener(VideoListener listener);
 
 
     /**
     /**
      * Removes a listener of video events.
      * Removes a listener of video events.
      *
      *
      * @param listener The listener to unregister.
      * @param listener The listener to unregister.
+     * @deprecated Use {@link #removeListener(Listener)}.
      */
      */
+    @Deprecated
     void removeVideoListener(VideoListener listener);
     void removeVideoListener(VideoListener listener);
 
 
     /**
     /**
@@ -388,14 +396,18 @@ public interface ExoPlayer extends Player {
      * Registers an output to receive text events.
      * Registers an output to receive text events.
      *
      *
      * @param listener The output to register.
      * @param listener The output to register.
+     * @deprecated Use {@link #addListener(Listener)}.
      */
      */
+    @Deprecated
     void addTextOutput(TextOutput listener);
     void addTextOutput(TextOutput listener);
 
 
     /**
     /**
      * Removes a text output.
      * Removes a text output.
      *
      *
      * @param listener The output to remove.
      * @param listener The output to remove.
+     * @deprecated Use {@link #removeListener(Listener)}.
      */
      */
+    @Deprecated
     void removeTextOutput(TextOutput listener);
     void removeTextOutput(TextOutput listener);
 
 
     /** Returns the current {@link Cue Cues}. This list may be empty. */
     /** Returns the current {@link Cue Cues}. This list may be empty. */
@@ -409,24 +421,38 @@ public interface ExoPlayer extends Player {
      * Adds a {@link MetadataOutput} to receive metadata.
      * Adds a {@link MetadataOutput} to receive metadata.
      *
      *
      * @param output The output to register.
      * @param output The output to register.
+     * @deprecated Use {@link #addListener(Listener)}.
      */
      */
+    @Deprecated
     void addMetadataOutput(MetadataOutput output);
     void addMetadataOutput(MetadataOutput output);
 
 
     /**
     /**
      * Removes a {@link MetadataOutput}.
      * Removes a {@link MetadataOutput}.
      *
      *
      * @param output The output to remove.
      * @param output The output to remove.
+     * @deprecated Use {@link #removeListener(Listener)}.
      */
      */
+    @Deprecated
     void removeMetadataOutput(MetadataOutput output);
     void removeMetadataOutput(MetadataOutput output);
   }
   }
 
 
   /** The device component of an {@link ExoPlayer}. */
   /** The device component of an {@link ExoPlayer}. */
   interface DeviceComponent {
   interface DeviceComponent {
 
 
-    /** Adds a listener to receive device events. */
+    /**
+     * Adds a listener to receive device events.
+     *
+     * @deprecated Use {@link #addListener(Listener)}.
+     */
+    @Deprecated
     void addDeviceListener(DeviceListener listener);
     void addDeviceListener(DeviceListener listener);
 
 
-    /** Removes a listener of device events. */
+    /**
+     * Removes a listener of device events.
+     *
+     * @deprecated Use {@link #removeListener(Listener)}.
+     */
+    @Deprecated
     void removeDeviceListener(DeviceListener listener);
     void removeDeviceListener(DeviceListener listener);
 
 
     /** Gets the device information. */
     /** Gets the device information. */

robolectricutils/src/main/java/com/google/android/exoplayer2/robolectric/TestPlayerRunHelper.java

@@ -281,15 +281,15 @@ public class TestPlayerRunHelper {
   public static void runUntilRenderedFirstFrame(SimpleExoPlayer player) throws TimeoutException {
   public static void runUntilRenderedFirstFrame(SimpleExoPlayer player) throws TimeoutException {
     verifyMainTestThread(player);
     verifyMainTestThread(player);
     AtomicBoolean receivedCallback = new AtomicBoolean(false);
     AtomicBoolean receivedCallback = new AtomicBoolean(false);
-    VideoListener listener =
-        new VideoListener() {
+    Player.Listener listener =
+        new Player.Listener() {
           @Override
           @Override
           public void onRenderedFirstFrame() {
           public void onRenderedFirstFrame() {
             receivedCallback.set(true);
             receivedCallback.set(true);
-            player.removeVideoListener(this);
+            player.removeListener(this);
           }
           }
         };
         };
-    player.addVideoListener(listener);
+    player.addListener(listener);
     runMainLooperUntil(receivedCallback::get);
     runMainLooperUntil(receivedCallback::get);
   }
   }