# 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
public final class PlayerFence
```

<br />

*** ** * ** ***

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

Kotlin users should strongly prefer directly calling the suspending `https://developer.android.com/reference/androidx/media3/common/Player` extension functions like `https://developer.android.com/reference/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/androidx/media3/test/utils/PlayerFence#futureWhen(androidx.media3.common.Player)`.

## Summary

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

## Public methods

### entersPlaybackState

```
public final @NonNull ListenableFuture<Void> entersPlaybackState(@Player.State int targetState)
```

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

If the player is already in the provided `https://developer.android.com/reference/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. |

### futureWhen

```
public static final @NonNull PlayerFence futureWhen(@NonNull Player 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/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/androidx/media3/test/utils/PlayerFence#withTimeoutMs(kotlin.Long)`.

- Futures returned from the returned `PlayerFence` will fail immediately when the `https://developer.android.com/reference/androidx/media3/common/Player` encounters a non-fatal error (such as `https://developer.android.com/reference/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/androidx/media3/test/utils/PlayerFence#ignoringNonFatalErrors()`.

### ignoringNonFatalErrors

```
public final @NonNull PlayerFence ignoringNonFatalErrors()
```

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

```
public final @NonNull ListenableFuture<Void> isPlaying(boolean targetIsPlaying)
```

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

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

### passesContentPosition

```
public final @NonNull ListenableFuture<Void> passesContentPosition(long targetPositionMs)
```

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

See `https://developer.android.com/reference/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

```
public final @NonNull ListenableFuture<Void> rendersFirstFrame()
```

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

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

### withSupervision

```
public final @NonNull ListenableFuture<@NonNull T> <T extends Object> withSupervision(@NonNull ListenableFuture<@NonNull T> future)
```

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

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

### withTimeoutMs

```
public final @NonNull PlayerFence withTimeoutMs(long timeoutMs)
```

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