Add detection for player stuck in BUFFERING state

This detection needs to happen on the application thread to capture
cases where the playback thread is not responsive (e.g. stuck in a
MediaCodec call).

As this is only a last resort fallback timeout, we choose a really
large value of 10 minutes at which we should be able to see some
progress even for data sources with long timeouts and retries. As
some apps may intentionally choose to wait for longer, this value
is configurable on ExoPlayer.

PiperOrigin-RevId: 785864050

Author: tonihei

RELEASENOTES.md

@@ -9,6 +9,10 @@
         and consequently restore Player's volume before and after setting it to
         zero.
 *   ExoPlayer:
+    *   Add a stuck buffering detection that triggers a `StuckPlayerException`
+        player error after 10 minutes of `STATE_BUFFERING` while trying to play
+        and no buffering progress. This timeout is configurable in
+        `ExoPlayer.Builder.setStuckBufferingDetectionTimeoutMs` if required.
     *   Ensure renderers don't consume data from the next playlist item more
         than 10 seconds before the end of the current item.
     *   Add getter for shuffle mode to the `ExoPlayer` interface

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayer.java

@@ -245,6 +245,7 @@ final class Builder {
     /* package */ LivePlaybackSpeedControl livePlaybackSpeedControl;
     /* package */ long releaseTimeoutMs;
     /* package */ long detachSurfaceTimeoutMs;
+    /* package */ int stuckBufferingDetectionTimeoutMs;
     /* package */ boolean pauseAtEndOfMediaItems;
     /* package */ boolean usePlatformDiagnostics;
     @Nullable /* package */ PlaybackLooperProvider playbackLooperProvider;
@@ -294,6 +295,8 @@ final class Builder {
      *   <li>{@code maxSeekToPreviousPositionMs}: {@link C#DEFAULT_MAX_SEEK_TO_PREVIOUS_POSITION_MS}
      *   <li>{@code releaseTimeoutMs}: {@link #DEFAULT_RELEASE_TIMEOUT_MS}
      *   <li>{@code detachSurfaceTimeoutMs}: {@link #DEFAULT_DETACH_SURFACE_TIMEOUT_MS}
+     *   <li>{@code stuckBufferingDetectionTimeoutMs}: {@link
+     *       #DEFAULT_STUCK_BUFFERING_DETECTION_TIMEOUT_MS}
      *   <li>{@code pauseAtEndOfMediaItems}: {@code false}
      *   <li>{@code usePlatformDiagnostics}: {@code true}
      *   <li>{@link Clock}: {@link Clock#DEFAULT}
@@ -458,6 +461,7 @@ private Builder(
       clock = Clock.DEFAULT;
       releaseTimeoutMs = DEFAULT_RELEASE_TIMEOUT_MS;
       detachSurfaceTimeoutMs = DEFAULT_DETACH_SURFACE_TIMEOUT_MS;
+      stuckBufferingDetectionTimeoutMs = DEFAULT_STUCK_BUFFERING_DETECTION_TIMEOUT_MS;
       usePlatformDiagnostics = true;
       playerName = "";
       priority = C.PRIORITY_PLAYBACK;
@@ -951,6 +955,26 @@ public Builder setDetachSurfaceTimeoutMs(long detachSurfaceTimeoutMs) {
       return this;
     }
 
+    /**
+     * Sets the timeout after which the player is assumed stuck buffering if it's in {@link
+     * Player#STATE_BUFFERING} and no loading progress is made, in milliseconds.
+     *
+     * <p>If this timeout is triggered, the player will transition to an error state with a {@link
+     * StuckPlayerException} using {@link StuckPlayerException#STUCK_BUFFERING_NO_PROGRESS}.
+     *
+     * @param stuckBufferingDetectionTimeoutMs The timeout after which the player is assumed stuck
+     *     buffering, in milliseconds.
+     * @return This builder.
+     * @throws IllegalStateException If {@link #build()} has already been called.
+     */
+    @CanIgnoreReturnValue
+    @UnstableApi
+    public Builder setStuckBufferingDetectionTimeoutMs(int stuckBufferingDetectionTimeoutMs) {
+      checkState(!buildCalled);
+      this.stuckBufferingDetectionTimeoutMs = stuckBufferingDetectionTimeoutMs;
+      return this;
+    }
+
     /**
      * Sets whether to pause playback at the end of each media item.
      *
@@ -1128,6 +1152,9 @@ public ExoPlayer build() {
   /** The default timeout for detaching a surface from the player, in milliseconds. */
   @UnstableApi long DEFAULT_DETACH_SURFACE_TIMEOUT_MS = 2_000;
 
+  /** The default timeout for detecting whether playback is stuck buffering, in milliseconds. */
+  @UnstableApi int DEFAULT_STUCK_BUFFERING_DETECTION_TIMEOUT_MS = 600_000;
+
   /**
    * Equivalent to {@link Player#getPlayerError()}, except the exception is guaranteed to be an
    * {@link ExoPlaybackException}.

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/ExoPlayerImpl.java

@@ -177,6 +177,7 @@
   private final long detachSurfaceTimeoutMs;
   @Nullable private final SuitableOutputChecker suitableOutputChecker;
   private final BackgroundThreadStateHandler<Integer> audioSessionIdState;
+  private final StuckPlayerDetector stuckPlayerDetector;
 
   private @RepeatMode int repeatMode;
   private boolean shuffleModeEnabled;
@@ -449,6 +450,13 @@ public ExoPlayerImpl(ExoPlayer.Builder builder, @Nullable Player wrappingPlayer)
       videoSize = VideoSize.UNKNOWN;
       surfaceSize = Size.UNKNOWN;
 
+      stuckPlayerDetector =
+          new StuckPlayerDetector(
+              /* player= */ this,
+              componentListener,
+              clock,
+              builder.stuckBufferingDetectionTimeoutMs);
+
       internalPlayer.setScrubbingModeParameters(scrubbingModeParameters);
       internalPlayer.setAudioAttributes(audioAttributes, builder.handleAudioFocus);
       sendRendererMessage(TRACK_TYPE_AUDIO, MSG_SET_AUDIO_ATTRIBUTES, audioAttributes);
@@ -1040,6 +1048,7 @@ public void release() {
     if (suitableOutputChecker != null) {
       suitableOutputChecker.disable();
     }
+    stuckPlayerDetector.release();
     if (!internalPlayer.release()) {
       // One of the renderers timed out releasing its resources.
       listeners.sendEvent(
@@ -3085,7 +3094,8 @@ private final class ComponentListener
           SphericalGLSurfaceView.VideoSurfaceListener,
           AudioBecomingNoisyManager.EventListener,
           StreamVolumeManager.Listener,
-          AudioOffloadListener {
+          AudioOffloadListener,
+          StuckPlayerDetector.Callback {
 
     // VideoRendererEventListener implementation
 
@@ -3355,6 +3365,15 @@ public void onStreamVolumeChanged(int streamVolume, boolean streamMuted) {
     public void onSleepingForOffloadChanged(boolean sleepingForOffload) {
       updateWakeAndWifiLock();
     }
+
+    // StuckPlayerDetector.Callback implementation.
+
+    @Override
+    public void onStuckPlayerDetected(StuckPlayerException exception) {
+      stopInternal(
+          ExoPlaybackException.createForUnexpected(
+              exception, PlaybackException.ERROR_CODE_TIMEOUT));
+    }
   }
 
   /** Listeners that are called on the playback thread. */

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/StuckPlayerDetector.java

@@ -0,0 +1,155 @@
+/*
+ * Copyright 2025 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 androidx.media3.exoplayer;
+
+import android.os.Handler;
+import android.os.Message;
+import androidx.annotation.Nullable;
+import androidx.media3.common.Player;
+import androidx.media3.common.Timeline;
+import androidx.media3.common.util.Clock;
+import androidx.media3.common.util.HandlerWrapper;
+import java.util.Objects;
+
+/** Detection logic for stuck playbacks. */
+/* package */ final class StuckPlayerDetector implements Player.Listener, Handler.Callback {
+
+  /** Callback notified when the player appears stuck. */
+  public interface Callback {
+
+    /**
+     * Called when the player appears to be stuck.
+     *
+     * @param exception The {@link StuckPlayerException}.
+     */
+    void onStuckPlayerDetected(StuckPlayerException exception);
+  }
+
+  private static final int MSG_STUCK_BUFFERING_TIMEOUT = 1;
+
+  private final Player player;
+  private final Callback callback;
+  private final Clock clock;
+  private final Timeline.Period period;
+  private final HandlerWrapper handler;
+  private final StuckBufferingDetector stuckBufferingDetector;
+
+  /**
+   * Creates the stuck player detector.
+   *
+   * <p>Must be called on the player's {@link Player#getApplicationLooper()}.
+   *
+   * @param player The {@link Player} to monitor.
+   * @param callback The {@link Callback} to notify of stuck playbacks.
+   * @param clock The {@link Clock}.
+   * @param stuckBufferingTimeoutMs The timeout after which the player is assumed stuck buffering if
+   *     it's buffering and no loading progress is made, in milliseconds.
+   */
+  public StuckPlayerDetector(
+      Player player, Callback callback, Clock clock, int stuckBufferingTimeoutMs) {
+    this.player = player;
+    this.callback = callback;
+    this.clock = clock;
+    this.period = new Timeline.Period();
+    this.handler = clock.createHandler(player.getApplicationLooper(), /* callback= */ this);
+    this.stuckBufferingDetector = new StuckBufferingDetector(stuckBufferingTimeoutMs);
+    player.addListener(this);
+  }
+
+  /** Releases the stuck player detector. */
+  public void release() {
+    handler.removeCallbacksAndMessages(/* token= */ null);
+    player.removeListener(this);
+  }
+
+  @Override
+  public void onEvents(Player player, Player.Events events) {
+    stuckBufferingDetector.update();
+  }
+
+  @Override
+  public boolean handleMessage(Message message) {
+    switch (message.what) {
+      case MSG_STUCK_BUFFERING_TIMEOUT:
+        stuckBufferingDetector.update();
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  private final class StuckBufferingDetector {
+
+    private final int stuckBufferingTimeoutMs;
+
+    @Nullable private Object periodUid;
+    private int adGroupIndex;
+    private int adIndexInAdGroup;
+    private long bufferedPositionInPeriodMs;
+    private boolean isBuffering;
+    private long startRealtimeMs;
+
+    public StuckBufferingDetector(int stuckBufferingTimeoutMs) {
+      this.stuckBufferingTimeoutMs = stuckBufferingTimeoutMs;
+    }
+
+    public void update() {
+      if (player.getPlaybackState() != Player.STATE_BUFFERING
+          || !player.getPlayWhenReady()
+          || player.getPlaybackSuppressionReason() != Player.PLAYBACK_SUPPRESSION_REASON_NONE) {
+        // Preconditions for stuck buffering not met. Clear any pending timeout and ignore.
+        if (isBuffering) {
+          handler.removeMessages(MSG_STUCK_BUFFERING_TIMEOUT);
+        }
+        isBuffering = false;
+        return;
+      }
+      Timeline timeline = player.getCurrentTimeline();
+      @Nullable
+      Object periodUid =
+          timeline.isEmpty() ? null : timeline.getUidOfPeriod(player.getCurrentPeriodIndex());
+      int adGroupIndex = player.getCurrentAdGroupIndex();
+      int adIndexInAdGroup = player.getCurrentAdIndexInAdGroup();
+      long bufferedPositionInPeriodMs = player.getBufferedPosition();
+      if (periodUid != null) {
+        bufferedPositionInPeriodMs -=
+            timeline.getPeriodByUid(periodUid, period).getPositionInWindowMs();
+      }
+      long nowRealtimeMs = clock.elapsedRealtime();
+      if (isBuffering
+          && Objects.equals(periodUid, this.periodUid)
+          && adGroupIndex == this.adGroupIndex
+          && adIndexInAdGroup == this.adIndexInAdGroup
+          && bufferedPositionInPeriodMs == this.bufferedPositionInPeriodMs) {
+        // Still the same state, keep current timeout.
+        if (nowRealtimeMs - startRealtimeMs >= stuckBufferingTimeoutMs) {
+          callback.onStuckPlayerDetected(
+              new StuckPlayerException(StuckPlayerException.STUCK_BUFFERING_NO_PROGRESS));
+        }
+      } else {
+        // Restart the timeout from the current time.
+        isBuffering = true;
+        startRealtimeMs = nowRealtimeMs;
+        this.periodUid = periodUid;
+        this.adGroupIndex = adGroupIndex;
+        this.adIndexInAdGroup = adIndexInAdGroup;
+        this.bufferedPositionInPeriodMs = bufferedPositionInPeriodMs;
+        handler.removeMessages(MSG_STUCK_BUFFERING_TIMEOUT);
+        handler.sendEmptyMessageDelayed(MSG_STUCK_BUFFERING_TIMEOUT, stuckBufferingTimeoutMs);
+      }
+    }
+  }
+}

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/StuckPlayerException.java

@@ -18,6 +18,7 @@
 import static java.lang.annotation.ElementType.TYPE_USE;
 
 import androidx.annotation.IntDef;
+import androidx.annotation.Nullable;
 import androidx.media3.common.Player;
 import androidx.media3.common.util.UnstableApi;
 import java.lang.annotation.Documented;
@@ -39,17 +40,24 @@ public final class StuckPlayerException extends IllegalStateException {
    */
   public static final int STUCK_BUFFERING_NOT_LOADING = 0;
 
+  /**
+   * The player is stuck because it's in {@link Player#STATE_BUFFERING}, but no loading progress is
+   * made and the player is also not able to become ready.
+   */
+  public static final int STUCK_BUFFERING_NO_PROGRESS = 1;
+
   /**
    * The type of stuck playback. One of:
    *
    * <ul>
    *   <li>{@link #STUCK_BUFFERING_NOT_LOADING}
+   *   <li>{@link #STUCK_BUFFERING_NO_PROGRESS}
    * </ul>
    */
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @Target(TYPE_USE)
-  @IntDef({STUCK_BUFFERING_NOT_LOADING})
+  @IntDef({STUCK_BUFFERING_NOT_LOADING, STUCK_BUFFERING_NO_PROGRESS})
   public @interface StuckType {}
 
   /** The type of stuck playback. */
@@ -65,10 +73,29 @@ public StuckPlayerException(@StuckType int stuckType) {
     this.stuckType = stuckType;
   }
 
+  @Override
+  public boolean equals(@Nullable Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (obj == null || getClass() != obj.getClass()) {
+      return false;
+    }
+    StuckPlayerException other = (StuckPlayerException) obj;
+    return this.stuckType == other.stuckType;
+  }
+
+  @Override
+  public int hashCode() {
+    return stuckType;
+  }
+
   private static String getMessage(@StuckType int stuckType) {
     switch (stuckType) {
       case STUCK_BUFFERING_NOT_LOADING:
         return "Player stuck buffering and not loading";
+      case STUCK_BUFFERING_NO_PROGRESS:
+        return "Player stuck buffering with no progress";
       default:
         throw new IllegalStateException();
     }