# PlayerFence

Artifact: [androidx.media3:media3-test-utils](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/test/utils/PlayerFence.kt+class:androidx.media3.test.utils.PlayerFence)

*** ** * ** ***


```
@UnstableApi
class PlayerFence
```

<br />

*** ** * ** ***

A Java-compatible fluent API for waiting for certain `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` conditions.

Kotlin users should strongly prefer directly calling the suspending `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` extension functions like `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/package-summary#(androidx.media3.common.Player).awaitPlaybackState(kotlin.Int,kotlin.Boolean,kotlin.time.Duration)` instead.

Instances are created via `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#futureWhen(androidx.media3.common.Player)`.

## Summary

| ### Public companion functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#futureWhen(androidx.media3.common.Player)(player: https://developer.android.com/reference/kotlin/androidx/media3/common/Player)` Entry point for Java callers to get a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` for a `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` condition. |

| ### Public functions |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html?>` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#entersPlaybackState(kotlin.Int)(targetState: @https://developer.android.com/reference/kotlin/androidx/media3/common/Player.State https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Returns a future that completes when the player enters the provided `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#entersPlaybackState(kotlin.Int)`. |
| `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#ignoringNonFatalErrors()()` Returns a new instance that will not fail the future on non-fatal errors. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html?>` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#isPlaying(kotlin.Boolean)(targetIsPlaying: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Returns a future that completes when the player's `https://developer.android.com/reference/kotlin/androidx/media3/common/Player#isPlaying()` value matches `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#isPlaying(kotlin.Boolean)`. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html?>` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#passesContentPosition(kotlin.Long)(targetPositionMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Returns a future that completes when the content position reaches (or passes) `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#passesContentPosition(kotlin.Long)` in the current media item. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/java/lang/Void.html?>` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#rendersFirstFrame()()` Returns a future that completes when `https://developer.android.com/reference/kotlin/androidx/media3/common/Player.Listener#onRenderedFirstFrame()` is invoked. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<T>` | `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#withSupervision(com.google.common.util.concurrent.ListenableFuture)(future: https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<T>)` Returns a future that completes when the provided `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#withSupervision(com.google.common.util.concurrent.ListenableFuture)` completes, supervising it against `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` playback errors and timeouts. |
| `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence` | `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#withTimeoutMs(kotlin.Long)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Returns a new instance that will fail the future if the condition is not met within the specified timeout. |

## Public companion functions

### futureWhen

```
fun futureWhen(player: Player): PlayerFence
```

Entry point for Java callers to get a `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` for a `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` condition.

- Futures returned from the returned `PlayerFence` will fail after a default timeout (10 seconds, or 30 seconds if running on an emulator). This can be customized using `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#withTimeoutMs(kotlin.Long)`.

- Futures returned from the returned `PlayerFence` will fail immediately when the `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` encounters a non-fatal error (such as `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/analytics/AnalyticsListener#onAudioCodecError(androidx.media3.exoplayer.analytics.AnalyticsListener.EventTime,java.lang.Exception)`). This can be customized using `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#ignoringNonFatalErrors()`.

## Public functions

### entersPlaybackState

```
fun entersPlaybackState(targetState: @Player.State Int): ListenableFuture<Void?>
```

Returns a future that completes when the player enters the provided `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#entersPlaybackState(kotlin.Int)`.

If the player is already in the provided `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#entersPlaybackState(kotlin.Int)`, the future completes immediately.

Must be called on the player's application looper thread.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if not called on the player's application looper thread. |

### ignoringNonFatalErrors

```
fun ignoringNonFatalErrors(): PlayerFence
```

Returns a new instance that will not fail the future on non-fatal errors.

By default, futures will fail if a non-fatal error (e.g. loading error) occurs while waiting.

### isPlaying

```
fun isPlaying(targetIsPlaying: Boolean): ListenableFuture<Void?>
```

Returns a future that completes when the player's `https://developer.android.com/reference/kotlin/androidx/media3/common/Player#isPlaying()` value matches `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#isPlaying(kotlin.Boolean)`.

Must be called on the player's application looper thread.

### passesContentPosition

```
fun passesContentPosition(targetPositionMs: Long): ListenableFuture<Void?>
```

Returns a future that completes when the content position reaches (or passes) `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#passesContentPosition(kotlin.Long)` in the current media item.

See `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/package-summary#(androidx.media3.common.Player).awaitContentPositionAtLeast(kotlin.Long,kotlin.Boolean,kotlin.time.Duration)` for assumptions made by this condition.

Must be called on the player's application looper thread.

### rendersFirstFrame

```
fun rendersFirstFrame(): ListenableFuture<Void?>
```

Returns a future that completes when `https://developer.android.com/reference/kotlin/androidx/media3/common/Player.Listener#onRenderedFirstFrame()` is invoked.

Must be called on the player's application looper thread.

### withSupervision

```
fun <T : Any?> withSupervision(future: ListenableFuture<T>): ListenableFuture<T>
```

Returns a future that completes when the provided `https://developer.android.com/reference/kotlin/androidx/media3/test/utils/PlayerFence#withSupervision(com.google.common.util.concurrent.ListenableFuture)` completes, supervising it against `https://developer.android.com/reference/kotlin/androidx/media3/common/Player` playback errors and timeouts.

Must be called on the player's application looper thread.

### withTimeoutMs

```
fun withTimeoutMs(timeoutMs: Long): PlayerFence
```

Returns a new instance that will fail the future if the condition is not met within the specified timeout.