PlayerFence

Kotlin |Java

@UnstableApi
class PlayerFence

A Java-compatible fluent API for waiting for certain Player conditions.

Kotlin users should strongly prefer directly calling the suspending Player extension functions like awaitPlaybackState instead.

Instances are created via futureWhen.

Summary

Public companion functions
`PlayerFence`	`futureWhen(player: Player)` Entry point for Java callers to get a `ListenableFuture` for a `Player` condition.

Public functions
`ListenableFuture<Void?>`	`entersPlaybackState(targetState: @Player.State Int)` Returns a future that completes when the player enters the provided `targetState`.
`PlayerFence`	`ignoringNonFatalErrors()` Returns a new instance that will not fail the future on non-fatal errors.
`ListenableFuture<Void?>`	`isPlaying(targetIsPlaying: Boolean)` Returns a future that completes when the player's `Player.isPlaying` value matches `targetIsPlaying`.
`ListenableFuture<Void?>`	`passesContentPosition(targetPositionMs: Long)` Returns a future that completes when the content position reaches (or passes) `targetPositionMs` in the current media item.
`ListenableFuture<Void?>`	`rendersFirstFrame()` Returns a future that completes when `Player.Listener.onRenderedFirstFrame` is invoked.
`PlayerFence`	`withTimeoutMs(timeoutMs: Long)` Returns a new instance that will fail the future if the condition is not met within the specified timeout.

fun futureWhen(player: Player): PlayerFence

Entry point for Java callers to get a ListenableFuture for a 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 PlayerFence.withTimeoutMs.
Futures returned from the returned PlayerFence will fail immediately when the Player encounters a non-fatal error (such as AnalyticsListener.onAudioCodecError). This can be customized using PlayerFence.ignoringNonFatalErrors.

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

Returns a future that completes when the player enters the provided targetState.

If the player is already in the provided targetState, the future completes immediately.

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

Throws
`IllegalStateException`	if not called on the player's application looper thread.

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.

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

Returns a future that completes when the player's Player.isPlaying value matches targetIsPlaying.

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

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

Returns a future that completes when the content position reaches (or passes) targetPositionMs in the current media item.

See Player.awaitContentPositionAtLeast for assumptions made by this condition.

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

fun rendersFirstFrame(): ListenableFuture<Void?>

Returns a future that completes when Player.Listener.onRenderedFirstFrame is invoked.

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

fun withTimeoutMs(timeoutMs: Long): PlayerFence

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