[ui-compose] Add ProgressStateWithTickInterval for position/duration

This ProgressState stateholder is customized to be used by text-based UI elements that are ticking with the media-time. The "grid" for ticking is chosen as the multiples of tickInterval (e.g. 1s, 2s, 3s) and the `position` is only updated then.

Text-based UI element is likely to be a string, whose granularity (e.g. for HH:MM:SS seconds are the highest granularity) should be matched with the tickInterval to help syncronise recomposition while keeping it as low as possible. This helps avoid the responsibility of the consumer to use derivedState to cap the recompositions.

[demo-compose] Add `TextProgressIndicator`, i.e. textual representations of progress, to `demo-compose`.

PiperOrigin-RevId: 777567494

Author: oceanjules

RELEASENOTES.md

@@ -31,6 +31,10 @@
     *   Fix bug where `PlayerSurface` inside re-usable components like
         `LazyColumn` didn't work correctly
         ([#2493](https://github.com/androidx/media/issues/2493)).
+    *   Add `ProgressStateWithTickInterval` class and the corresponding
+        `rememberProgressStateWithTickInterval` Composable to
+        `media3-ui-compose` module. This state holder is used in `demo-compose`
+        to display the current position and duration in text form.
 *   Downloads:
 *   OkHttp extension:
 *   Cronet extension:

demos/compose/src/main/java/androidx/media3/demo/compose/buttons/ExtraControls.kt

@@ -18,10 +18,12 @@ package androidx.media3.demo.compose.buttons
 
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.media3.common.Player
+import androidx.media3.demo.compose.indicator.TextProgressIndicator
 
 @Composable
 internal fun ExtraControls(player: Player, modifier: Modifier = Modifier) {
@@ -30,6 +32,8 @@ internal fun ExtraControls(player: Player, modifier: Modifier = Modifier) {
     horizontalArrangement = Arrangement.Center,
     verticalAlignment = Alignment.CenterVertically,
   ) {
+    TextProgressIndicator(player, Modifier.align(Alignment.CenterVertically))
+    Spacer(Modifier.weight(1f))
     PlaybackSpeedPopUpButton(player)
     ShuffleButton(player)
     RepeatButton(player)

demos/compose/src/main/java/androidx/media3/demo/compose/indicator/TextProgressIndicator.kt

@@ -0,0 +1,58 @@
+/*
+ * 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
+ *
+ *      https://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.demo.compose.indicator
+
+import androidx.annotation.IntRange
+import androidx.compose.foundation.text.BasicText
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.derivedStateOf
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.media3.common.Player
+import androidx.media3.common.util.Util.getStringForTime
+import androidx.media3.ui.compose.state.ProgressStateWithTickInterval
+import androidx.media3.ui.compose.state.rememberProgressStateWithTickInterval
+
+/**
+ * An example of a progress indicator that represents the [Player's][Player]
+ * [ProgressStateWithTickInterval] in textual form.
+ *
+ * It displays the up-to-date current position and duration of the media at the granularity of the
+ * provided [timeStepSeconds]. For example, for shorter videos, a 1-second granularity
+ * (`timeSecondsStep = 1`) might be more appropriate, whereas for a multiple-hour long movie, a
+ * 1-minute granularity (`timeSecondsStep = 60`) might be enough. Tuning this parameter can help you
+ * avoid unnecessary recompositions.
+ *
+ * @param timeStepSeconds Delta of the media time that constitutes a progress step, in seconds.
+ */
+@Composable
+fun TextProgressIndicator(
+  player: Player,
+  modifier: Modifier = Modifier,
+  @IntRange(from = 0) timeStepSeconds: Int = 1,
+) {
+  val progressState =
+    rememberProgressStateWithTickInterval(
+      player,
+      tickIntervalMs = timeStepSeconds.toLong().times(1000),
+    )
+  val current = getStringForTime(progressState.currentPositionMs)
+  // duration will not change as often as current position
+  val duration by remember { derivedStateOf { getStringForTime(progressState.durationMs) } }
+  BasicText("$current - $duration", modifier)
+}

libraries/common/src/main/java/androidx/media3/common/util/Util.java

@@ -2788,6 +2788,19 @@ public static String getStringForTime(StringBuilder builder, Formatter formatter
         : formatter.format("%s%02d:%02d", prefix, minutes, seconds).toString();
   }
 
+  /**
+   * Returns the specified millisecond time formatted as a string.
+   *
+   * @param timeMs The time to format as a string, in milliseconds.
+   * @return The time formatted as a string.
+   */
+  @UnstableApi
+  public static String getStringForTime(long timeMs) {
+    StringBuilder builder = new StringBuilder();
+    Formatter formatter = new Formatter(builder, Locale.getDefault());
+    return getStringForTime(builder, formatter, timeMs);
+  }
+
   /**
    * Escapes a string so that it's safe for use as a file or directory name on at least FAT32
    * filesystems. FAT32 is the most restrictive of all filesystems still commonly used today.

libraries/common/src/test/java/androidx/media3/common/util/UtilTest.java

@@ -1314,9 +1314,35 @@ public void tableExists_withNonExistingTable() {
   }
 
   @Test
-  public void getStringForTime_withNegativeTime_setsNegativePrefix() {
-    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ -35000))
-        .isEqualTo("-00:35");
+  public void getStringForTime_withRangeOfValues() {
+    assertThat(getStringForTime(C.TIME_UNSET)).isEqualTo("00:00");
+    assertThat(getStringForTime(0)).isEqualTo("00:00");
+    assertThat(getStringForTime(413)).isEqualTo("00:00");
+    assertThat(getStringForTime(800)).isEqualTo("00:01");
+    assertThat(getStringForTime(10_000)).isEqualTo("00:10");
+    assertThat(getStringForTime(65_000)).isEqualTo("01:05");
+    assertThat(getStringForTime(3_661_000)).isEqualTo("1:01:01");
+    assertThat(getStringForTime(-4_000)).isEqualTo("-00:04");
+  }
+
+  @Test
+  public void getStringForTime_withFormatter_withRangeOfValues() {
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ C.TIME_UNSET))
+        .isEqualTo("00:00");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 0))
+        .isEqualTo("00:00");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 413))
+        .isEqualTo("00:00");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 800))
+        .isEqualTo("00:01");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 10_000))
+        .isEqualTo("00:10");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 65_000))
+        .isEqualTo("01:05");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ 3_661_000))
+        .isEqualTo("1:01:01");
+    assertThat(getStringForTime(new StringBuilder(), new Formatter(), /* timeMs= */ -4_000))
+        .isEqualTo("-00:04");
   }
 
   @Test

libraries/ui_compose/build.gradle

@@ -56,6 +56,7 @@ dependencies {
     // Remove the version number once b/385138624 is fixed, GMaven doesn't resolve the BOM above
     api 'androidx.compose.foundation:foundation:1.7.6'
 
+    testImplementation 'androidx.compose.ui:ui-test-android:1.8.2'
     testImplementation 'androidx.compose.ui:ui-test'
     testImplementation 'androidx.compose.ui:ui-test-junit4'
     testImplementation project(modulePrefix + 'test-utils')

libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/ProgressStateJob.kt

@@ -0,0 +1,146 @@
+/*
+ * 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
+ *
+ *      https://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.ui.compose.state
+
+import androidx.annotation.VisibleForTesting
+import androidx.compose.runtime.withFrameMillis
+import androidx.media3.common.C
+import androidx.media3.common.Player
+import androidx.media3.common.listen
+import androidx.media3.common.util.Assertions.checkState
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+
+internal class ProgressStateJob(
+  private val player: Player,
+  private val scope: CoroutineScope,
+  private val intervalMsSupplier: () -> Long,
+  private val scheduledTask: () -> Unit,
+) {
+  private var updateJob: Job? = null
+
+  /**
+   * Subscribes to updates from [Player.Events] to track changes of progress-related information in
+   * an asynchronous way.
+   */
+  internal suspend fun observeProgress(): Nothing = coroutineScope {
+    // otherwise we don't update on recomposition of UI, only on Player.Events
+    cancelPendingUpdatesAndRelaunch()
+    player.listen { events ->
+      if (
+        events.containsAny(
+          Player.EVENT_IS_PLAYING_CHANGED,
+          Player.EVENT_POSITION_DISCONTINUITY,
+          Player.EVENT_TIMELINE_CHANGED,
+          Player.EVENT_PLAYBACK_PARAMETERS_CHANGED,
+          Player.EVENT_AVAILABLE_COMMANDS_CHANGED,
+        )
+      ) {
+        scheduledTask()
+        if (player.isCommandAvailable(Player.COMMAND_GET_CURRENT_MEDIA_ITEM)) {
+          cancelPendingUpdatesAndRelaunch()
+        } else {
+          updateJob?.cancel()
+        }
+      }
+    }
+  }
+
+  internal fun cancelPendingUpdatesAndRelaunch() {
+    updateJob?.cancel()
+    scheduledTask()
+    updateJob =
+      scope.launch {
+        while (isActive) {
+          smartDelay()
+          scheduledTask()
+        }
+      }
+  }
+
+  /**
+   * Delay the polling of the [Player] by the time delta that corresponds to the interval supplied
+   * by [intervalMsSupplier]. If the duration of one step is zero, the polling is suspended until
+   * the next frame is requested, preventing unnecessarily frequent updates that will not be visible
+   * on the screen.
+   *
+   * Playback speed is taken into account as well, since it expands or shrinks the effective media
+   * duration.
+   */
+  private suspend fun smartDelay() {
+    val oneStepDurationMs = intervalMsSupplier()
+    checkState(
+      oneStepDurationMs >= 0 || oneStepDurationMs == C.TIME_UNSET,
+      "Provided intervalMsSupplier is negative: $oneStepDurationMs",
+    )
+    if (player.isPlaying && oneStepDurationMs != C.TIME_UNSET) {
+      if (oneStepDurationMs < MIN_UPDATE_INTERVAL_MS * player.playbackParameters.speed) {
+        // oneStepDurationMs == 0 is a requested continuous update,
+        // otherwise throttled by Recomposition frequency
+        withFrameMillis {}
+      } else {
+        val mediaTimeToNextStepMs = oneStepDurationMs - player.currentPosition % oneStepDurationMs
+        // Convert the specified interval to wall-clock time
+        var realTimeToNextStepMs = mediaTimeToNextStepMs / player.playbackParameters.speed
+        // Prevent unnecessarily short sleep which results in increased scheduledTask() frequency
+        if (realTimeToNextStepMs < MIN_UPDATE_INTERVAL_MS) {
+          realTimeToNextStepMs += oneStepDurationMs / player.playbackParameters.speed
+        }
+        // Prevent infinite delays by 0
+        delay(realTimeToNextStepMs.toLong().coerceAtLeast(1L))
+      }
+    } else if (
+      (player.playbackState != Player.STATE_ENDED && player.playbackState != Player.STATE_IDLE) ||
+        oneStepDurationMs == C.TIME_UNSET
+    ) {
+      delay(PAUSED_UPDATE_INTERVAL_MS)
+    }
+  }
+}
+
+internal fun getCurrentPositionMsOrDefault(player: Player): Long {
+  return if (player.isCommandAvailable(Player.COMMAND_GET_CURRENT_MEDIA_ITEM)) {
+    player.currentPosition
+  } else {
+    0
+  }
+}
+
+internal fun getBufferedPositionMsOrDefault(player: Player): Long {
+  return if (player.isCommandAvailable(Player.COMMAND_GET_CURRENT_MEDIA_ITEM)) {
+    player.bufferedPosition
+  } else {
+    0
+  }
+}
+
+internal fun getDurationMsOrDefault(player: Player): Long {
+  return if (player.isCommandAvailable(Player.COMMAND_GET_CURRENT_MEDIA_ITEM)) {
+    player.duration
+  } else {
+    C.TIME_UNSET
+  }
+}
+
+// Taking highest frame rate as 120fps, interval is 1000/120
+private const val MIN_UPDATE_INTERVAL_MS = 8L
+@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
+const val PAUSED_UPDATE_INTERVAL_MS = 1000L