Make onPlayerError take a PlaybackException

PiperOrigin-RevId: 380174672

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

@@ -32,7 +32,6 @@ import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.appcompat.app.AppCompatActivity;
 import com.google.android.exoplayer2.C;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
 import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
@@ -424,7 +423,7 @@ public class PlayerActivity extends AppCompatActivity
     }
 
     @Override
-    public void onPlayerError(@NonNull ExoPlaybackException e) {
+    public void onPlayerError(@NonNull PlaybackException e) {
       if (e.errorCode == PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW) {
         player.seekToDefaultPosition();
         player.prepare();

docs/listening-to-player-events.md

@@ -67,35 +67,36 @@ public void onIsPlayingChanged(boolean isPlaying) {
 ### Playback errors ###
 
 Errors that cause playback to fail can be received by implementing
-`onPlayerError(ExoPlaybackException error)` in a registered
+`onPlayerError(PlaybackException error)` in a registered
 `Player.Listener`. When a failure occurs, this method will be called
 immediately before the playback state transitions to `Player.STATE_IDLE`.
 Failed or stopped playbacks can be retried by calling `ExoPlayer.retry`.
 
-[`ExoPlaybackException`][] has a `type` field, as well as corresponding getter
+Note that some [`Player`][] implementations pass instances of subclasses of
-methods that return cause exceptions providing more information about the
+`PlaybackException` to provide additional information about the failure. For
-failure. The example below shows how to detect when a playback has failed due to
+example, [`ExoPlayer`][] passes [`ExoPlaybackException`][] which has `type`,
-a HTTP networking issue.
+`rendererIndex` and other ExoPlayer-specific fields.
+
+The following example shows how to detect when a playback has failed due to an
+HTTP networking issue:
 
 ~~~
 @Override
-public void onPlayerError(ExoPlaybackException error) {
+public void onPlayerError(PlaybackException error) {
-  if (error.type == ExoPlaybackException.TYPE_SOURCE) {
+  Throwable cause = error.getCause();
-    IOException cause = error.getSourceException();
+  if (cause instanceof HttpDataSourceException) {
-    if (cause instanceof HttpDataSourceException) {
+    // An HTTP error occurred.
-      // An HTTP error occurred.
+    HttpDataSourceException httpError = (HttpDataSourceException) cause;
-      HttpDataSourceException httpError = (HttpDataSourceException) cause;
+    // This is the request for which the error occurred.
-      // This is the request for which the error occurred.
+    DataSpec requestDataSpec = httpError.dataSpec;
-      DataSpec requestDataSpec = httpError.dataSpec;
+    // It's possible to find out more about the error both by casting and by
-      // It's possible to find out more about the error both by casting and by
+    // querying the cause.
-      // querying the cause.
+    if (httpError instanceof HttpDataSource.InvalidResponseCodeException) {
-      if (httpError instanceof HttpDataSource.InvalidResponseCodeException) {
+      // Cast to InvalidResponseCodeException and retrieve the response code,
-        // Cast to InvalidResponseCodeException and retrieve the response code,
+      // message and headers.
-        // message and headers.
+    } else {
-      } else {
+      // Try calling httpError.getCause() to retrieve the underlying cause,
-        // Try calling httpError.getCause() to retrieve the underlying cause,
+      // although note that it may be null.
-        // although note that it may be null.
-      }
     }
   }
 }
@@ -228,6 +229,8 @@ player
 [`Player.Listener`]: {{ site.exo_sdk }}/Player.Listener.html
 [Javadoc]: {{ site.exo_sdk }}/Player.Listener.html
 [`Individual callbacks vs onEvents`]: #individual-callbacks-vs-onevents
+[`Player`]: {{ site.exo_sdk }}/Player.html
+[`ExoPlayer`]: {{ site.exo_sdk }}/ExoPlayer.html
 [`ExoPlaybackException`]: {{ site.exo_sdk }}/ExoPlaybackException.html
 [log output]: event-logger.html
 [`Parameters`]: {{ site.exo_sdk }}/trackselection/DefaultTrackSelector.Parameters.html

docs/live-streaming.md

@@ -142,7 +142,7 @@ the demo app exemplifies this approach.
 
 ~~~
 @Override
-public void onPlayerError(ExoPlaybackException e) {
+public void onPlayerError(PlaybackException e) {
   if (e.errorCode == PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW) {
     // Re-initialize player at the current live window default position.
     player.seekToDefaultPosition();

extensions/flac/src/androidTest/java/com/google/android/exoplayer2/ext/flac/FlacPlaybackTest.java

@@ -23,8 +23,8 @@ import android.os.Looper;
 import androidx.annotation.Nullable;
 import androidx.test.core.app.ApplicationProvider;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.RenderersFactory;
@@ -96,7 +96,7 @@ public class FlacPlaybackTest {
     private final AudioSink audioSink;
 
     @Nullable private SimpleExoPlayer player;
-    @Nullable private ExoPlaybackException playbackException;
+    @Nullable private PlaybackException playbackException;
 
     public TestPlaybackRunnable(Uri uri, Context context, AudioSink audioSink) {
       this.uri = uri;
@@ -129,7 +129,7 @@ public class FlacPlaybackTest {
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException error) {
+    public void onPlayerError(PlaybackException error) {
       playbackException = error;
     }
 

extensions/ima/src/main/java/com/google/android/exoplayer2/ext/ima/AdTagLoader.java

@@ -51,8 +51,8 @@ import com.google.ads.interactivemedia.v3.api.player.ContentProgressProvider;
 import com.google.ads.interactivemedia.v3.api.player.VideoAdPlayer;
 import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
 import com.google.android.exoplayer2.C;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.ExoPlayerLibraryInfo;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Timeline;
 import com.google.android.exoplayer2.source.ads.AdPlaybackState;
@@ -514,7 +514,7 @@ import java.util.Map;
   }
 
   @Override
-  public void onPlayerError(ExoPlaybackException error) {
+  public void onPlayerError(PlaybackException error) {
     if (imaAdState != IMA_AD_STATE_NONE) {
       AdMediaInfo adMediaInfo = checkNotNull(imaAdMediaInfo);
       for (int i = 0; i < adCallbacks.size(); i++) {

extensions/leanback/src/main/java/com/google/android/exoplayer2/ext/leanback/LeanbackPlayerAdapter.java

@@ -255,15 +255,16 @@ public final class LeanbackPlayerAdapter extends PlayerAdapter implements Runnab
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException exception) {
+    public void onPlayerError(PlaybackException exception) {
       Callback callback = getCallback();
       if (errorMessageProvider != null) {
         Pair<Integer, String> errorMessage = errorMessageProvider.getErrorMessage(exception);
         callback.onError(LeanbackPlayerAdapter.this, errorMessage.first, errorMessage.second);
       } else {
-        // TODO: Conditionally assign the rendererIndex depending on whether the exception is an
+        int rendererIndex = C.INDEX_UNSET;
-        // ExoPlaybackException once onPlayerError takes a PlaybackException.
+        if (exception instanceof ExoPlaybackException) {
-        int rendererIndex = exception.rendererIndex;
+          rendererIndex = ((ExoPlaybackException) exception).rendererIndex;
+        }
         callback.onError(
             LeanbackPlayerAdapter.this,
             exception.errorCode,

extensions/media2/src/main/java/com/google/android/exoplayer2/ext/media2/PlayerWrapper.java

@@ -27,8 +27,8 @@ import androidx.media2.common.SessionPlayer;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.ControlDispatcher;
 import com.google.android.exoplayer2.DefaultControlDispatcher;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.PlaybackParameters;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Timeline;
@@ -597,7 +597,7 @@ import java.util.List;
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException error) {
+    public void onPlayerError(PlaybackException error) {
       updateSessionPlayerState();
     }
 

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

@@ -23,8 +23,8 @@ import android.os.Looper;
 import androidx.annotation.Nullable;
 import androidx.test.core.app.ApplicationProvider;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.RenderersFactory;
@@ -79,7 +79,7 @@ public class OpusPlaybackTest {
     private final Uri uri;
 
     @Nullable private SimpleExoPlayer player;
-    @Nullable private ExoPlaybackException playbackException;
+    @Nullable private PlaybackException playbackException;
 
     public TestPlaybackRunnable(Uri uri, Context context) {
       this.uri = uri;
@@ -109,7 +109,7 @@ public class OpusPlaybackTest {
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException error) {
+    public void onPlayerError(PlaybackException error) {
       playbackException = error;
     }
 

extensions/vp9/src/androidTest/java/com/google/android/exoplayer2/ext/vp9/VpxPlaybackTest.java

@@ -24,8 +24,8 @@ import android.os.Looper;
 import androidx.annotation.Nullable;
 import androidx.test.core.app.ApplicationProvider;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.RenderersFactory;
@@ -107,7 +107,7 @@ public class VpxPlaybackTest {
     private final Uri uri;
 
     @Nullable private SimpleExoPlayer player;
-    @Nullable private ExoPlaybackException playbackException;
+    @Nullable private PlaybackException playbackException;
 
     public TestPlaybackRunnable(Uri uri, Context context) {
       this.uri = uri;
@@ -144,7 +144,7 @@ public class VpxPlaybackTest {
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException error) {
+    public void onPlayerError(PlaybackException error) {
       playbackException = error;
     }
 

library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java

@@ -681,7 +681,7 @@ public class ForwardingPlayer implements Player {
     }
 
     @Override
-    public void onPlayerError(ExoPlaybackException error) {
+    public void onPlayerError(PlaybackException error) {
       eventListener.onPlayerError(error);
     }
 

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

@@ -267,9 +267,12 @@ public interface Player {
      * <p>{@link #onEvents(Player, Events)} will also be called to report this event along with
      * other events that happen in the same {@link Looper} message queue iteration.
      *
+     * <p>Implementations of Player may pass an instance of a subclass of {@link PlaybackException}
+     * to this method in order to include more information about the error.
+     *
      * @param error The error.
      */
-    default void onPlayerError(ExoPlaybackException error) {}
+    default void onPlayerError(PlaybackException error) {}
 
     /**
      * @deprecated Use {@link #onPositionDiscontinuity(PositionInfo, PositionInfo, int)} instead.
@@ -1488,14 +1491,14 @@ public interface Player {
 
   /**
    * Returns the error that caused playback to fail. This is the same error that will have been
-   * reported via {@link Listener#onPlayerError(ExoPlaybackException)} at the time of failure. It
+   * reported via {@link Listener#onPlayerError(PlaybackException)} at the time of failure. It can
-   * can be queried using this method until the player is re-prepared.
+   * be queried using this method until the player is re-prepared.
    *
    * <p>Note that this method will always return {@code null} if {@link #getPlaybackState()} is not
    * {@link #STATE_IDLE}.
    *
    * @return The error, or {@code null}.
-   * @see Listener#onPlayerError(ExoPlaybackException)
+   * @see Listener#onPlayerError(PlaybackException)
    */
   @Nullable
   PlaybackException getPlayerError();

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

@@ -245,8 +245,7 @@ public final class PlayerMessage {
 
   /**
    * Sends the message. If the target throws an {@link ExoPlaybackException} then it is propagated
-   * out of the player as an error using {@link
+   * out of the player as an error using {@link Player.Listener#onPlayerError(PlaybackException)}.
-   * Player.Listener#onPlayerError(ExoPlaybackException)}.
    *
    * @return This message.
    * @throws IllegalStateException If this message has already been sent.

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

@@ -26,6 +26,7 @@ import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.Format;
 import com.google.android.exoplayer2.MediaItem;
 import com.google.android.exoplayer2.MediaMetadata;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.PlaybackParameters;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Player.PlaybackSuppressionReason;
@@ -708,15 +709,22 @@ public class AnalyticsCollector
   }
 
   @Override
-  public final void onPlayerError(ExoPlaybackException error) {
+  public final void onPlayerError(PlaybackException error) {
-    EventTime eventTime =
+    EventTime eventTime = null;
-        error.mediaPeriodId != null
+    if (error instanceof ExoPlaybackException) {
-            ? generateEventTime(new MediaPeriodId(error.mediaPeriodId))
+      ExoPlaybackException exoError = (ExoPlaybackException) error;
-            : generateCurrentPlayerMediaPeriodEventTime();
+      if (exoError.mediaPeriodId != null) {
+        eventTime = generateEventTime(new MediaPeriodId(exoError.mediaPeriodId));
+      }
+    }
+    if (eventTime == null) {
+      eventTime = generateCurrentPlayerMediaPeriodEventTime();
+    }
+    EventTime finalEventTime = eventTime;
     sendEvent(
         eventTime,
         AnalyticsListener.EVENT_PLAYER_ERROR,
-        listener -> listener.onPlayerError(eventTime, error));
+        listener -> listener.onPlayerError(finalEventTime, error));
   }
 
   // Calling deprecated callback.

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

@@ -650,6 +650,9 @@ public interface AnalyticsListener {
   /**
    * Called when a fatal player error occurred.
    *
+   * <p>Implementations of {@link Player} may pass an instance of a subclass of {@link
+   * PlaybackException} to this method in order to include more information about the error.
+   *
    * @param eventTime The event time.
    * @param error The error.
    */

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

@@ -21,6 +21,7 @@ import androidx.annotation.Nullable;
 import com.google.android.exoplayer2.C;
 import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.Format;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.PlaybackParameters;
 import com.google.android.exoplayer2.Player;
 import java.lang.annotation.Documented;
@@ -122,7 +123,7 @@ public interface AudioSink {
      * wishes to do so.
      *
      * <p>Fatal errors that cannot be recovered will be reported wrapped in a {@link
-     * ExoPlaybackException} by {@link Player.Listener#onPlayerError(ExoPlaybackException)}.
+     * ExoPlaybackException} by {@link Player.Listener#onPlayerError(PlaybackException)}.
      *
      * @param audioSinkError The error that occurred. Typically an {@link InitializationException},
      *     a {@link WriteException}, or an {@link UnexpectedDiscontinuityException}.

library/rtsp/src/test/java/com/google/android/exoplayer2/source/rtsp/RtspPlaybackTest.java

@@ -20,8 +20,8 @@ import static com.google.common.truth.Truth.assertThat;
 import android.net.Uri;
 import androidx.test.core.app.ApplicationProvider;
 import androidx.test.ext.junit.runners.AndroidJUnit4;
-import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player.Listener;
 import com.google.android.exoplayer2.SimpleExoPlayer;
 import com.google.android.exoplayer2.robolectric.RobolectricUtil;
@@ -95,7 +95,7 @@ public final class RtspPlaybackTest {
       player.addListener(
           new Listener() {
             @Override
-            public void onPlayerError(ExoPlaybackException error) {
+            public void onPlayerError(PlaybackException error) {
               playbackError.set(error);
             }
           });

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

@@ -22,6 +22,7 @@ import static com.google.common.truth.Truth.assertThat;
 import android.os.Looper;
 import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.ExoPlayer;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.SimpleExoPlayer;
 import com.google.android.exoplayer2.Timeline;
@@ -199,8 +200,9 @@ public class TestPlayerRunHelper {
     Player.Listener listener =
         new Player.Listener() {
           @Override
-          public void onPlayerError(ExoPlaybackException error) {
+          public void onPlayerError(PlaybackException error) {
-            receivedError.set(error);
+            // ExoPlayer is guaranteed to throw an ExoPlaybackException.
+            receivedError.set((ExoPlaybackException) error);
             player.removeListener(this);
           }
         };

testutils/src/main/java/com/google/android/exoplayer2/testutil/ExoPlayerTestRunner.java

@@ -29,6 +29,7 @@ import com.google.android.exoplayer2.ExoPlaybackException;
 import com.google.android.exoplayer2.Format;
 import com.google.android.exoplayer2.LoadControl;
 import com.google.android.exoplayer2.MediaItem;
+import com.google.android.exoplayer2.PlaybackException;
 import com.google.android.exoplayer2.Player;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.RenderersFactory;
@@ -692,7 +693,7 @@ public final class ExoPlayerTestRunner implements Player.Listener, ActionSchedul
   }
 
   @Override
-  public void onPlayerError(ExoPlaybackException error) {
+  public void onPlayerError(PlaybackException error) {
     handleException(error);
   }