Add fractional seek tolerance option to scrubbing mode

PiperOrigin-RevId: 756898758

Author: icbaker

RELEASENOTES.md

@@ -9,6 +9,7 @@
         scrubber bar around). The behavior of scrubbing mode can be customized
         with `setScrubbingModeParameters(..)` on `ExoPlayer` and
         `ExoPlayer.Builder`.
+    *   Allow customizing fractional seek tolerance in scrubbing mode.
     *   Fix bug where prepare errors in the content of `AdsMediaSource` may be
         never reported ([#2337](https://github.com/androidx/media/issues/2337)).
     *   Fix memory leak in `MergingMediaSource`, for example used when

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

@@ -76,7 +76,9 @@
 import androidx.media3.exoplayer.upstream.BandwidthMeter;
 import androidx.media3.exoplayer.video.VideoFrameMetadataListener;
 import com.google.common.collect.ImmutableList;
+import com.google.common.math.DoubleMath;
 import java.io.IOException;
+import java.math.RoundingMode;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -223,6 +225,7 @@ public interface PlaybackInfoUpdateListener {
   private final AudioFocusManager audioFocusManager;
   private SeekParameters seekParameters;
   private ScrubbingModeParameters scrubbingModeParameters;
+  @Nullable private SeekParameters scrubbingModeSeekParameters;
   private boolean scrubbingModeEnabled;
   private boolean seekIsPendingWhileScrubbing;
   @Nullable private SeekPosition queuedSeekWhileScrubbing;
@@ -1601,7 +1604,7 @@ private void seekToInternal(SeekPosition seekPosition, boolean incrementAcks)
               && newPeriodPositionUs != 0) {
             newPeriodPositionUs =
                 playingPeriodHolder.mediaPeriod.getAdjustedSeekPositionUs(
-                    newPeriodPositionUs, seekParameters);
+                    newPeriodPositionUs, getSeekParameters(window.durationUs));
           }
           if (Util.usToMs(newPeriodPositionUs) == Util.usToMs(playbackInfo.positionUs)
               && (playbackInfo.playbackState == Player.STATE_BUFFERING
@@ -1639,6 +1642,27 @@ private void seekToInternal(SeekPosition seekPosition, boolean incrementAcks)
     }
   }
 
+  private SeekParameters getSeekParameters(long durationUs) {
+    if (!scrubbingModeEnabled
+        || durationUs == C.TIME_UNSET
+        || scrubbingModeParameters.fractionalSeekToleranceBefore == null
+        || scrubbingModeParameters.fractionalSeekToleranceAfter == null) {
+      return seekParameters;
+    }
+    long toleranceBeforeUs =
+        DoubleMath.roundToLong(
+            scrubbingModeParameters.fractionalSeekToleranceBefore * durationUs, RoundingMode.FLOOR);
+    long toleranceAfterUs =
+        DoubleMath.roundToLong(
+            scrubbingModeParameters.fractionalSeekToleranceAfter * durationUs, RoundingMode.FLOOR);
+    if (scrubbingModeSeekParameters == null
+        || scrubbingModeSeekParameters.toleranceBeforeUs != toleranceBeforeUs
+        || scrubbingModeSeekParameters.toleranceAfterUs != toleranceAfterUs) {
+      scrubbingModeSeekParameters = new SeekParameters(toleranceBeforeUs, toleranceAfterUs);
+    }
+    return scrubbingModeSeekParameters;
+  }
+
   private long seekToPeriodPosition(
       MediaPeriodId periodId, long periodPositionUs, boolean forceBufferingState)
       throws ExoPlaybackException {
@@ -1744,8 +1768,6 @@ private void setSeekParametersInternal(SeekParameters seekParameters) {
 
   private void setScrubbingModeEnabledInternal(boolean scrubbingModeEnabled)
       throws ExoPlaybackException {
-    this.scrubbingModeEnabled = scrubbingModeEnabled;
-    applyScrubbingModeParameters();
     if (!scrubbingModeEnabled) {
       seekIsPendingWhileScrubbing = false;
       handler.removeMessages(MSG_SEEK_COMPLETED_IN_SCRUBBING_MODE);
@@ -1755,6 +1777,8 @@ private void setScrubbingModeEnabledInternal(boolean scrubbingModeEnabled)
         queuedSeekWhileScrubbing = null;
       }
     }
+    this.scrubbingModeEnabled = scrubbingModeEnabled;
+    applyScrubbingModeParameters();
   }
 
   private void setScrubbingModeParametersInternal(ScrubbingModeParameters scrubbingModeParameters)

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

@@ -15,12 +15,16 @@
  */
 package androidx.media3.exoplayer;
 
+import static androidx.media3.common.util.Assertions.checkArgument;
+
+import androidx.annotation.FloatRange;
 import androidx.annotation.Nullable;
 import androidx.media3.common.C;
 import androidx.media3.common.C.TrackType;
 import androidx.media3.common.util.UnstableApi;
 import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import java.util.Objects;
 import java.util.Set;
 
 /**
@@ -42,6 +46,8 @@ public final class ScrubbingModeParameters {
    */
   public static final class Builder {
     private ImmutableSet<@TrackType Integer> disabledTrackTypes;
+    @Nullable private Double fractionalSeekToleranceBefore;
+    @Nullable private Double fractionalSeekToleranceAfter;
 
     /** Creates an instance. */
     public Builder() {
@@ -50,6 +56,8 @@ public Builder() {
 
     private Builder(ScrubbingModeParameters scrubbingModeParameters) {
       this.disabledTrackTypes = scrubbingModeParameters.disabledTrackTypes;
+      this.fractionalSeekToleranceBefore = scrubbingModeParameters.fractionalSeekToleranceBefore;
+      this.fractionalSeekToleranceAfter = scrubbingModeParameters.fractionalSeekToleranceAfter;
     }
 
     /**
@@ -69,6 +77,37 @@ public Builder setDisabledTrackTypes(Set<@TrackType Integer> disabledTrackTypes)
       return this;
     }
 
+    /**
+     * Sets the fraction of the media duration to use for {@link SeekParameters#toleranceBeforeUs}
+     * and {@link SeekParameters#toleranceAfterUs} when scrubbing.
+     *
+     * Pass {@code null} for both values to use the {@linkplain ExoPlayer#getSeekParameters()
+     * player-level seek parameters} when scrubbing.
+     *
+     * Defaults to {code null} for both values, so all seeks are exact (this may change in a
+     * future release).
+     *
+     * See {@link ScrubbingModeParameters#fractionalSeekToleranceBefore} and {@link
+     * ScrubbingModeParameters#fractionalSeekToleranceAfter}.
+     *
+     * @param toleranceBefore The fraction of the media duration to use for {@link
+     *     SeekParameters#toleranceBeforeUs}, or null to use the player-level seek parameters.
+     * @param toleranceAfter The fraction of the media duration to use for {@link
+     *     SeekParameters#toleranceAfterUs}, or null to use the player-level seek parameters.
+     * @return This builder for convenience.
+     */
+    @CanIgnoreReturnValue
+    public Builder setFractionalSeekTolerance(
+        @Nullable @FloatRange(from = 0, to = 1) Double toleranceBefore,
+        @Nullable @FloatRange(from = 0, to = 1) Double toleranceAfter) {
+      checkArgument((toleranceBefore == null) == (toleranceAfter == null));
+      checkArgument(toleranceBefore == null || (toleranceBefore >= 0 && toleranceBefore <= 1));
+      checkArgument(toleranceAfter == null || (toleranceAfter >= 0 && toleranceAfter <= 1));
+      this.fractionalSeekToleranceBefore = toleranceBefore;
+      this.fractionalSeekToleranceAfter = toleranceAfter;
+      return this;
+    }
+
     /** Returns the built {@link ScrubbingModeParameters}. */
     public ScrubbingModeParameters build() {
       return new ScrubbingModeParameters(this);
@@ -78,8 +117,32 @@ public ScrubbingModeParameters build() {
   /** Which track types will be disabled in scrubbing mode. */
   public final ImmutableSet<@TrackType Integer> disabledTrackTypes;
 
+  /**
+   * The fraction of the media duration to use for {@link SeekParameters#toleranceBeforeUs} when
+   * scrubbing.
+   *
+   * If this is {@code null} or the media duration is not known then the {@linkplain
+   * ExoPlayer#getSeekParameters()} non-scrubbing seek parameters} are used.
+   */
+  @Nullable
+  @FloatRange(from = 0, to = 1)
+  public final Double fractionalSeekToleranceBefore;
+
+  /**
+   * The fraction of the media duration to use for {@link SeekParameters#toleranceAfterUs} when
+   * scrubbing.
+   *
+   * If this is {@code null} or the media duration is not known then the {@linkplain
+   * ExoPlayer#getSeekParameters()} non-scrubbing seek parameters} are used.
+   */
+  @Nullable
+  @FloatRange(from = 0, to = 1)
+  public final Double fractionalSeekToleranceAfter;
+
   private ScrubbingModeParameters(Builder builder) {
     this.disabledTrackTypes = builder.disabledTrackTypes;
+    this.fractionalSeekToleranceBefore = builder.fractionalSeekToleranceBefore;
+    this.fractionalSeekToleranceAfter = builder.fractionalSeekToleranceAfter;
   }
 
   /** Returns a {@link Builder} initialized with the values from this instance. */
@@ -93,11 +156,14 @@ public boolean equals(@Nullable Object o) {
       return false;
     }
     ScrubbingModeParameters that = (ScrubbingModeParameters) o;
-    return disabledTrackTypes.equals(that.disabledTrackTypes);
+    return disabledTrackTypes.equals(that.disabledTrackTypes)
+        && Objects.equals(fractionalSeekToleranceBefore, that.fractionalSeekToleranceBefore)
+        && Objects.equals(fractionalSeekToleranceAfter, that.fractionalSeekToleranceAfter);
   }
 
   @Override
   public int hashCode() {
-    return disabledTrackTypes.hashCode();
+    return Objects.hash(
+        disabledTrackTypes, fractionalSeekToleranceBefore, fractionalSeekToleranceAfter);
   }
 }

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/ExoPlayerScrubbingTest.java

@@ -349,7 +349,7 @@ public void scrubbingMode_disablesAudioTrack_masksTrackSelectionParameters() thr
   }
 
   @Test
-  public void customizeParameters_beforeScrubbingModeEnabled() throws Exception {
+  public void customizeDisabledTracks_beforeScrubbingModeEnabled() throws Exception {
     Timeline timeline = new FakeTimeline();
     ExoPlayer player =
         new TestExoPlayerBuilder(ApplicationProvider.getApplicationContext()).build();
@@ -381,7 +381,7 @@ public void customizeParameters_beforeScrubbingModeEnabled() throws Exception {
   }
 
   @Test
-  public void customizeParameters_duringScrubbingMode() throws Exception {
+  public void customizeDisabledTracks_duringScrubbingMode() throws Exception {
     Timeline timeline = new FakeTimeline();
     ExoPlayer player =
         new TestExoPlayerBuilder(ApplicationProvider.getApplicationContext()).build();
@@ -412,4 +412,52 @@ public void customizeParameters_duringScrubbingMode() throws Exception {
     player.release();
     surface.release();
   }
+
+  @Test
+  public void fractionalSeekTolerance_isPropagated() throws Exception {
+    Timeline timeline =
+        new FakeTimeline(
+            new TimelineWindowDefinition.Builder().setWindowPositionInFirstPeriodUs(0).build());
+    ExoPlayer player =
+        new TestExoPlayerBuilder(ApplicationProvider.getApplicationContext()).build();
+    Surface surface = new Surface(new SurfaceTexture(/* texName= */ 1));
+    player.setVideoSurface(surface);
+    Player.Listener mockListener = mock(Player.Listener.class);
+    player.addListener(mockListener);
+    player.setScrubbingModeParameters(
+        new ScrubbingModeParameters.Builder()
+            .setFractionalSeekTolerance(/* toleranceBefore= */ 0.1, /* toleranceAfter= */ 0.1)
+            .build());
+    player.setMediaSource(
+        new FakeMediaSource.Builder()
+            .setTimeline(timeline)
+            .setTrackDataFactory(
+                TrackDataFactory.samplesWithRateDurationAndKeyframeInterval(
+                    /* initialSampleTimeUs= */ 0,
+                    /* sampleRate= */ 30,
+                    /* durationUs= */ DEFAULT_WINDOW_DURATION_US,
+                    /* keyFrameInterval= */ 60))
+            .setSyncSampleTimesUs(new long[] {0, 2_000_000, 4_000_000, 6_000_000, 8_000_000})
+            .setFormats(ExoPlayerTestRunner.VIDEO_FORMAT)
+            .build());
+    player.prepare();
+    player.play();
+    advance(player).untilPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 1000);
+    VideoFrameMetadataListener mockVideoFrameMetadataListener =
+        mock(VideoFrameMetadataListener.class);
+    player.setVideoFrameMetadataListener(mockVideoFrameMetadataListener);
+
+    player.setScrubbingModeEnabled(true);
+    advance(player).untilPendingCommandsAreFullyHandled();
+    player.seekTo(2500);
+    advance(player).untilPosition(/* mediaItemIndex= */ 0, /* positionMs= */ 2000);
+    player.setScrubbingModeEnabled(false);
+    player.clearVideoFrameMetadataListener(mockVideoFrameMetadataListener);
+    advance(player).untilState(Player.STATE_ENDED);
+    player.release();
+    surface.release();
+
+    verify(mockVideoFrameMetadataListener)
+        .onVideoFrameAboutToBeRendered(eq(2_000_000L), anyLong(), any(), any());
+  }
 }