[ui-compose-material3] Add text progress Composable

The Composable underneath is `BasicText` which is not smart enough to ensure that dynamic text, like video timestamp, doesn't cause layout to reflow.

Usually, there are a couple of ways to ensure the width remains constant:
* `Monospaced` font (every character has the same width)
* `fontFeatureSettings` parameter of the `TextStyle` (each digit has the same width, normal characters remain proportional)
* `TextMeasurer` (measure the widest "worst-case" string like 88:88, apply that to all other numbers)

The default font on Android (Roboto) is well-designed, and the width differences between its numerals are subtle to the naked eye. What is making it harder to test in the demo app is the flexible `Spacer` that takes up the *remaining* space.

Ideally, adding the tests that check the width of various strings **would** show that, as of now, the implementation is width-independent and robust. The problem is that the Android test environment is intentionally designed to prevent this kind of test from working. It does **not** use the standard "Roboto" font, but a basic, non-proportional test font (i.e. all characters have the same width). This is done to prevent visual inconsistencies and flakiness in screenshot and UI tests. In fact, loading custom fonts in this environment is a known difficulty, so no matter what FontFamily we specify, the test environment will likely override it with a font that has fixed-width numerals.

Given all this, we shall still apply one of the fixes to ensure the solution will work on real world devices.

#cherrypick

PiperOrigin-RevId: 829452658

Author: oceanjules

RELEASENOTES.md

@@ -45,6 +45,9 @@
 *   UI:
     *   Use `BidiFormatter` to correctly display punctuation in RTL text
         subtitles ([#11214](https://github.com/google/ExoPlayer/issues/11214)).
+    *   Add `TimeText` composable to `media3-ui-compose-material3` for
+        displaying player progress in a textual form. It can be configured to
+        show the current position, duration, or remaining time.
 *   Downloads:
 *   OkHttp extension:
 *   Cronet extension:

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

@@ -23,6 +23,7 @@ import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.runtime.Composable
@@ -32,7 +33,6 @@ import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.unit.dp
 import androidx.media3.common.Player
 import androidx.media3.demo.compose.indicator.HorizontalLinearProgressIndicator
-import androidx.media3.demo.compose.indicator.TextProgressIndicator
 import androidx.media3.ui.compose.material3.buttons.MuteButton
 import androidx.media3.ui.compose.material3.buttons.NextButton
 import androidx.media3.ui.compose.material3.buttons.PlayPauseButton
@@ -41,6 +41,7 @@ import androidx.media3.ui.compose.material3.buttons.RepeatButton
 import androidx.media3.ui.compose.material3.buttons.SeekBackButton
 import androidx.media3.ui.compose.material3.buttons.SeekForwardButton
 import androidx.media3.ui.compose.material3.buttons.ShuffleButton
+import androidx.media3.ui.compose.material3.indicator.PositionAndDurationText
 
 @Composable
 private fun RowControls(
@@ -93,11 +94,12 @@ internal fun BoxScope.Controls(player: Player) {
   Column(Modifier.fillMaxWidth().align(Alignment.BottomCenter)) {
     HorizontalLinearProgressIndicator(player, Modifier.fillMaxWidth())
     Row(
-      modifier = Modifier.fillMaxWidth().background(Color.Gray.copy(alpha = 0.4f)),
-      horizontalArrangement = Arrangement.Center,
+      modifier =
+        Modifier.fillMaxWidth().background(Color.Gray.copy(alpha = 0.4f)).padding(start = 15.dp),
+      horizontalArrangement = Arrangement.Start,
       verticalAlignment = Alignment.CenterVertically,
     ) {
-      TextProgressIndicator(player, Modifier.align(Alignment.CenterVertically))
+      PositionAndDurationText(player)
       Spacer(Modifier.weight(1f))
       PlaybackSpeedPopUpButton(player)
       ShuffleButton(player)

libraries/ui_compose/src/main/java/androidx/media3/ui/compose/indicators/TimeText.kt

@@ -0,0 +1,70 @@
+/*
+ * 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.indicators
+
+import androidx.annotation.IntRange
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.ui.compose.state.ProgressStateWithTickInterval
+import androidx.media3.ui.compose.state.rememberProgressStateWithTickInterval
+import kotlinx.coroutines.CoroutineScope
+
+/**
+ * A Composable that provides player progress information to a content lambda, allowing for the
+ * creation of custom progress indicators.
+ *
+ * This function does not render any UI itself. Instead, it manages the state of the player's
+ * progress and exposes a [ProgressStateWithTickInterval] object to its [content] lambda. This
+ * allows for complete control over the layout and appearance of the progress display.
+ *
+ * Note that the reliance on [ProgressStateWithTickInterval] implies that the UI responsiveness and
+ * precision is optimised with the media-clock in mind. That makes it most suitable for displaying
+ * time-based text progress (rather than pixel-based slider/bar), hence the name of this Composable.
+ *
+ * It serves as a state provider, decoupling the logic of listening to player progress from the UI
+ * presentation, which is a flexible pattern recommended for building reusable Composables.
+ *
+ * Example usage:
+ * ```
+ * TimeText(player) {
+ *   // `this` is a `ProgressStateWithTickInterval`
+ *   val currentPosition = Util.getStringForTime(this.currentPositionMs)
+ *   val duration = Util.getStringForTime(this.durationMs)
+ *   Text("$currentPosition / $duration")
+ * }
+ * ```
+ *
+ * @param player The [Player] to get the progress from.
+ * @param tickIntervalMs The granularity of the progress updates in milliseconds. A smaller value
+ *   means more frequent updates, which may cause more recompositions.
+ * @param scope The [CoroutineScope] to use for listening to player progress updates.
+ * @param content A content lambda that receives a [ProgressStateWithTickInterval] as its receiver
+ *   scope, which can be used to build a custom UI.
+ */
+@UnstableApi
+@Composable
+fun TimeText(
+  player: Player,
+  @IntRange(from = 0) tickIntervalMs: Int = 1000,
+  scope: CoroutineScope = rememberCoroutineScope(),
+  content: @Composable ProgressStateWithTickInterval.() -> Unit,
+) {
+  rememberProgressStateWithTickInterval(player, tickIntervalMs = tickIntervalMs.toLong(), scope)
+    .content()
+}

libraries/ui_compose_material3/src/main/java/androidx/media3/ui/compose/material3/indicator/TimeText.kt

@@ -0,0 +1,213 @@
+/*
+ * 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.material3.indicator
+
+import androidx.compose.foundation.text.BasicText
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.TextStyle
+import androidx.media3.common.C
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.common.util.Util.getStringForTime
+import androidx.media3.ui.compose.indicators.TimeText
+import androidx.media3.ui.compose.state.ProgressStateWithTickInterval
+import kotlinx.coroutines.CoroutineScope
+
+/**
+ * A composable that displays the current position of the player.
+ *
+ * @param player The [Player] to get the position from.
+ * @param modifier The [Modifier] to be applied to the text.
+ * @param scope The [CoroutineScope] to use for listening to player progress updates.
+ */
+@UnstableApi
+@Composable
+fun PositionText(
+  player: Player,
+  modifier: Modifier = Modifier,
+  scope: CoroutineScope = rememberCoroutineScope(),
+) {
+  TimeText(player, modifier, TimeFormat.position(), scope)
+}
+
+/**
+ * A composable that displays the duration of the media.
+ *
+ * @param player The [Player] to get the duration from.
+ * @param modifier The [Modifier] to be applied to the text.
+ * @param scope The [CoroutineScope] to use for listening to player progress updates.
+ */
+@UnstableApi
+@Composable
+fun DurationText(
+  player: Player,
+  modifier: Modifier = Modifier,
+  scope: CoroutineScope = rememberCoroutineScope(),
+) {
+  TimeText(player, modifier, TimeFormat.duration(), scope)
+}
+
+/**
+ * A composable that displays the duration of the media.
+ *
+ * @param player The [Player] to get the duration from.
+ * @param modifier The [Modifier] to be applied to the text.
+ * @param showNegative Whether to display the remaining time with a minus sign.
+ * @param scope The [CoroutineScope] to use for listening to player progress updates.
+ */
+@UnstableApi
+@Composable
+fun RemainingDurationText(
+  player: Player,
+  modifier: Modifier = Modifier,
+  showNegative: Boolean = false,
+  scope: CoroutineScope = rememberCoroutineScope(),
+) {
+  TimeText(player, modifier, TimeFormat.remaining(showNegative), scope)
+}
+
+/**
+ * A composable that displays the duration of the media.
+ *
+ * @param player The [Player] to get the duration from.
+ * @param modifier The [Modifier] to be applied to the text.
+ * @param separator The separator string to be used between the current position and duration.
+ * @param scope The [CoroutineScope] to use for listening to player progress updates.
+ */
+@UnstableApi
+@Composable
+fun PositionAndDurationText(
+  player: Player,
+  modifier: Modifier = Modifier,
+  separator: String = " / ",
+  scope: CoroutineScope = rememberCoroutineScope(),
+) {
+  TimeText(player, modifier, TimeFormat.positionAndDuration(separator), scope)
+}
+
+/**
+ * Progress indicator that represents the [Player's][Player] progress state in textual form.
+ *
+ * It displays the up-to-date current position and duration of the media, formatted by
+ * [getStringForTime].
+ *
+ * @param player The [Player] to get the progress from.
+ * @param modifier The [Modifier] to be applied to the text.
+ * @param timeFormat The [TimeFormat] to use for displaying the time.
+ * @param scope Coroutine scope to listen to the progress updates from the player.
+ */
+@UnstableApi
+@Composable
+fun TimeText(
+  player: Player,
+  modifier: Modifier = Modifier,
+  timeFormat: TimeFormat,
+  scope: CoroutineScope = rememberCoroutineScope(),
+) {
+  TimeText(player, scope = scope) { TimeText(state = this, timeFormat, modifier) }
+}
+
+@Composable
+private fun TimeText(
+  state: ProgressStateWithTickInterval,
+  timeFormat: TimeFormat,
+  modifier: Modifier,
+) {
+  val text =
+    when (timeFormat.format) {
+      TimeFormat.POSITION -> getStringForTime(state.currentPositionMs)
+      TimeFormat.DURATION -> getStringForTime(state.durationMs)
+      TimeFormat.REMAINING ->
+        if (state.durationMs != C.TIME_UNSET) {
+          val remainingMs =
+            if (timeFormat.showNegative) {
+              state.currentPositionMs - state.durationMs
+            } else {
+              state.durationMs - state.currentPositionMs
+            }
+          getStringForTime(remainingMs)
+        } else {
+          getStringForTime(C.TIME_UNSET)
+        }
+
+      TimeFormat.POSITION_AND_DURATION ->
+        "${getStringForTime(state.currentPositionMs)}${timeFormat.separator}${getStringForTime(state.durationMs)}"
+
+      else -> throw IllegalStateException("Unrecognized TimeFormat ${timeFormat.format}")
+    }
+  BasicText(text, modifier, style = TextStyle(fontFeatureSettings = "tnum"))
+}
+
+/**
+ * A class for specifying the format of the time to be displayed by [TimeText].
+ *
+ * Instances of this class can be created using the factory methods, such as [position], [duration],
+ * [remaining], and [positionAndDuration].
+ */
+@UnstableApi
+class TimeFormat
+private constructor(
+  internal val format: Int,
+  internal val separator: String?,
+  internal val showNegative: Boolean,
+) {
+  companion object {
+    internal const val POSITION = 0
+    internal const val DURATION = 1
+    internal const val REMAINING = 2
+    internal const val POSITION_AND_DURATION = 3
+
+    /** Creates a [TimeFormat] that displays the current position of the player. */
+    fun position(): TimeFormat = TimeFormat(POSITION, null, false)
+
+    /** Creates a [TimeFormat] that displays the total duration of the media. */
+    fun duration(): TimeFormat = TimeFormat(DURATION, null, false)
+
+    /**
+     * Creates a [TimeFormat] that displays the remaining time of the media.
+     *
+     * @param showNegative Whether to display the remaining time with a minus sign.
+     */
+    fun remaining(showNegative: Boolean = false): TimeFormat =
+      TimeFormat(REMAINING, null, showNegative)
+
+    /**
+     * Creates a [TimeFormat] that displays both the current position and the total duration.
+     *
+     * @param separator The separator string to be used between the current position and duration.
+     */
+    fun positionAndDuration(separator: String = " / "): TimeFormat =
+      TimeFormat(POSITION_AND_DURATION, separator, false)
+  }
+
+  override fun equals(other: Any?): Boolean {
+    if (this === other) return true
+    if (other !is TimeFormat) return false
+    return format == other.format &&
+      separator == other.separator &&
+      showNegative == other.showNegative
+  }
+
+  override fun hashCode(): Int {
+    var result = format.hashCode()
+    result = 31 * result + (separator?.hashCode() ?: 0)
+    result = 31 * result + showNegative.hashCode()
+    return result
+  }
+}