AdPlaybackState

@UnstableApi
class AdPlaybackState

Represents ad group times and information on the state and URIs of ads within each ad group.

Instances are immutable. Call the with* methods to get new instances that have the required changes.

Summary

Nested types

Represents a group of ads, with information about their states.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = )
@IntDef(value = )
annotation AdPlaybackState.AdState

Represents the state of an ad in an ad group.

Constants
const Int

State for an ad that has a URL but has not yet been played.
const Int

State for an ad that could not be loaded.
const Int

State for an ad that was played in full.
const Int

State for an ad that was skipped.
const Int

State for an ad that does not yet have a URL.
const AdPlaybackState!

Ad playback state with no ads.

Public constructors
AdPlaybackState(adsId: Any!, adGroupTimesUs: LongArray!)

Creates a new ad playback state with the specified ad group times.

Public functions
Boolean

Returns whether the last ad group is a live postroll placeholder as inserted by withLivePostrollPlaceholderAppended.
Boolean
equals(o: Any?)
java-static AdPlaybackState!
fromAdPlaybackState(adsId: Any!, adPlaybackState: AdPlaybackState!)

Returns a copy of the ad playback state with the given ads ID.
java-static AdPlaybackState!
fromBundle(bundle: Bundle!)

Restores a AdPlaybackState from a Bundle.
AdPlaybackState.AdGroup!
getAdGroup(adGroupIndex: @IntRange(from = 0) Int)

Returns the specified AdGroup.
Int
getAdGroupIndexAfterPositionUs(positionUs: Long, periodDurationUs: Long)

Returns the index of the next ad group after positionUs that should be played.
Int
getAdGroupIndexForPositionUs(positionUs: Long, periodDurationUs: Long)

Returns the index of the ad group at or before positionUs that should be played before the content at positionUs.
Int
Boolean
isAdInErrorState(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
)

Returns whether the specified ad has been marked as in AD_STATE_ERROR.
Boolean

Whether the AdGroup at the given ad group index is a live postroll placeholder.
Bundle!

Returns a Bundle representing the information stored in this object.
String!
AdPlaybackState!
withAdCount(
    adGroupIndex: @IntRange(from = 0) Int,
    adCount: @IntRange(from = 1) Int
)

Returns an instance with the number of ads in adGroupIndex resolved to adCount.
AdPlaybackState!
withAdDurationsUs(adDurationUs: Array<LongArray!>!)

Returns an instance with the specified ad durations, in microseconds.
AdPlaybackState!
withAdDurationsUs(
    adGroupIndex: @IntRange(from = 0) Int,
    adDurationsUs: LongArray!
)

Returns an instance with the specified ad durations, in microseconds, in the specified ad group.
AdPlaybackState!
withAdGroupTimeUs(adGroupIndex: @IntRange(from = 0) Int, adGroupTimeUs: Long)

Returns an instance with the specified ad group time.
AdPlaybackState!
withAdLoadError(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
)

Returns an instance with the specified ad marked as having a load error.
AdPlaybackState!
withAdResumePositionUs(adResumePositionUs: Long)

Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.
AdPlaybackState!
withAvailableAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
)

Returns an instance with the specified ad marked as available.
AdPlaybackState!
withAvailableAdMediaItem(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int,
    mediaItem: MediaItem!
)

Returns an instance with the specified ad MediaItem and the ad marked as available.
AdPlaybackState!
withAvailableAdUri(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int,
    uri: Uri!
)

This function is deprecated.

Use withAvailableAdMediaItem instead.
AdPlaybackState!
withContentDurationUs(contentDurationUs: Long)

Returns an instance with the specified content duration, in microseconds.
AdPlaybackState!
withContentResumeOffsetUs(
    adGroupIndex: @IntRange(from = 0) Int,
    contentResumeOffsetUs: Long
)

Returns an instance with the specified contentResumeOffsetUs, in microseconds, for the specified ad group.
AdPlaybackState!
withIsServerSideInserted(
    adGroupIndex: @IntRange(from = 0) Int,
    isServerSideInserted: Boolean
)

Returns an instance with the specified value for isServerSideInserted in the specified ad group.
AdPlaybackState!
withLastAdRemoved(adGroupIndex: @IntRange(from = 0) Int)

Returns an instance with the last ad of the given ad group removed.
AdPlaybackState!

Appends a live postroll placeholder ad group to the ad playback state.
AdPlaybackState!
withNewAdGroup(adGroupIndex: @IntRange(from = 0) Int, adGroupTimeUs: Long)

Returns an instance with a new ad group.
AdPlaybackState!
withOriginalAdCount(
    adGroupIndex: @IntRange(from = 0) Int,
    originalAdCount: Int
)

Returns an instance with the specified value for originalCount in the specified ad group.
AdPlaybackState!
withPlayedAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
)

Returns an instance with the specified ad marked as played.
AdPlaybackState!
withRemovedAdGroupCount(removedAdGroupCount: @IntRange(from = 0) Int)

Returns an instance with the specified number of removed ad groups.
AdPlaybackState!
withResetAdGroup(adGroupIndex: @IntRange(from = 0) Int)

Returns an instance with all ads in the specified ad group reset from final states (played, skipped, error) to either available or unavailable, which allows to play them again.
AdPlaybackState!
withSkippedAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
)

Returns an instance with the specified ad marked as skipped.
AdPlaybackState!
withSkippedAdGroup(adGroupIndex: @IntRange(from = 0) Int)

Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

Public properties
Int

The number of ad groups.
Long

The position offset in the first unplayed ad at which to begin playback, in microseconds.
Any?

The opaque identifier for ads with which this instance is associated, or null if unset.
Long

The duration of the content period in microseconds, if known.
Int

The number of ad groups that have been removed.

Constants

AD_STATE_AVAILABLE

const val AD_STATE_AVAILABLE = 1: Int

State for an ad that has a URL but has not yet been played.

AD_STATE_ERROR

const val AD_STATE_ERROR = 4: Int

State for an ad that could not be loaded.

AD_STATE_PLAYED

const val AD_STATE_PLAYED = 3: Int

State for an ad that was played in full.

AD_STATE_SKIPPED

const val AD_STATE_SKIPPED = 2: Int

State for an ad that was skipped.

AD_STATE_UNAVAILABLE

const val AD_STATE_UNAVAILABLE = 0: Int

State for an ad that does not yet have a URL.

NONE

const val NONE: AdPlaybackState!

Ad playback state with no ads.

Public constructors

AdPlaybackState

AdPlaybackState(adsId: Any!, adGroupTimesUs: LongArray!)

Creates a new ad playback state with the specified ad group times.

Parameters
adsId: Any!

The opaque identifier for ads with which this instance is associated.
adGroupTimesUs: LongArray!

The times of ad groups in microseconds, relative to the start of the Timeline.Period they belong to. A final element with the value TIME_END_OF_SOURCE indicates that there is a postroll ad.

Public functions

endsWithLivePostrollPlaceHolder

fun endsWithLivePostrollPlaceHolder(): Boolean

Returns whether the last ad group is a live postroll placeholder as inserted by withLivePostrollPlaceholderAppended.

Returns
Boolean

Whether the ad playback state ends with a live postroll placeholder.

equals

fun equals(o: Any?): Boolean

fromAdPlaybackState

java-static fun fromAdPlaybackState(adsId: Any!, adPlaybackState: AdPlaybackState!): AdPlaybackState!

Returns a copy of the ad playback state with the given ads ID.

Parameters
adsId: Any!

The new ads ID.
adPlaybackState: AdPlaybackState!

The ad playback state to copy.
Returns
AdPlaybackState!

The new ad playback state.

fromBundle

java-static fun fromBundle(bundle: Bundle!): AdPlaybackState!

Restores a AdPlaybackState from a Bundle.

getAdGroup

fun getAdGroup(adGroupIndex: @IntRange(from = 0) Int): AdPlaybackState.AdGroup!

Returns the specified AdGroup.

getAdGroupIndexAfterPositionUs

fun getAdGroupIndexAfterPositionUs(positionUs: Long, periodDurationUs: Long): Int

Returns the index of the next ad group after positionUs that should be played. Returns INDEX_UNSET if there is no such ad group.

Parameters
positionUs: Long

The period position after which to find an ad group, in microseconds, or TIME_END_OF_SOURCE for the end of the stream (in which case there can be no ad group after the position).
periodDurationUs: Long

The duration of the containing timeline period, in microseconds, or TIME_UNSET if not known.
Returns
Int

The index of the ad group, or INDEX_UNSET.

getAdGroupIndexForPositionUs

fun getAdGroupIndexForPositionUs(positionUs: Long, periodDurationUs: Long): Int

Returns the index of the ad group at or before positionUs that should be played before the content at positionUs. Returns INDEX_UNSET if the ad group at or before positionUs has no ads remaining to be played, or if there is no such ad group.

Parameters
positionUs: Long

The period position at or before which to find an ad group, in microseconds, or TIME_END_OF_SOURCE for the end of the stream (in which case the index of any unplayed postroll ad group will be returned).
periodDurationUs: Long

The duration of the containing timeline period, in microseconds, or TIME_UNSET if not known.
Returns
Int

The index of the ad group, or INDEX_UNSET.

hashCode

fun hashCode(): Int

isAdInErrorState

fun isAdInErrorState(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
): Boolean

Returns whether the specified ad has been marked as in AD_STATE_ERROR.

isLivePostrollPlaceholder

fun isLivePostrollPlaceholder(adGroupIndex: Int): Boolean

Whether the AdGroup at the given ad group index is a live postroll placeholder.

Parameters
adGroupIndex: Int

The ad group index.
Returns
Boolean

True if the ad group at the given index is a live postroll placeholder, false if not.

toBundle

fun toBundle(): Bundle!

Returns a Bundle representing the information stored in this object.

It omits the adsId field so the adsId of instances restored by fromBundle will always be null.

toString

fun toString(): String!

withAdCount

fun withAdCount(
    adGroupIndex: @IntRange(from = 0) Int,
    adCount: @IntRange(from = 1) Int
): AdPlaybackState!

Returns an instance with the number of ads in adGroupIndex resolved to adCount. The ad count must be greater than zero.

withAdDurationsUs

fun withAdDurationsUs(adDurationUs: Array<LongArray!>!): AdPlaybackState!

Returns an instance with the specified ad durations, in microseconds.

Must only be used if removedAdGroupCount is 0.

withAdDurationsUs

fun withAdDurationsUs(
    adGroupIndex: @IntRange(from = 0) Int,
    adDurationsUs: LongArray!
): AdPlaybackState!

Returns an instance with the specified ad durations, in microseconds, in the specified ad group.

withAdGroupTimeUs

fun withAdGroupTimeUs(adGroupIndex: @IntRange(from = 0) Int, adGroupTimeUs: Long): AdPlaybackState!

Returns an instance with the specified ad group time.

Parameters
adGroupIndex: @IntRange(from = 0) Int

The index of the ad group.
adGroupTimeUs: Long

The new ad group time, in microseconds, or TIME_END_OF_SOURCE to indicate a postroll ad.
Returns
AdPlaybackState!

The updated ad playback state.

withAdLoadError

fun withAdLoadError(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
): AdPlaybackState!

Returns an instance with the specified ad marked as having a load error.

withAdResumePositionUs

fun withAdResumePositionUs(adResumePositionUs: Long): AdPlaybackState!

Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.

withAvailableAd

fun withAvailableAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
): AdPlaybackState!

Returns an instance with the specified ad marked as available.

Must not be called with client side inserted ad groups. Client side inserted ads should use withAvailableAdMediaItem.

Throws
java.lang.IllegalStateException

in case this methods is called on an ad group that is not server side inserted.

withAvailableAdMediaItem

fun withAvailableAdMediaItem(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int,
    mediaItem: MediaItem!
): AdPlaybackState!

Returns an instance with the specified ad MediaItem and the ad marked as available.

Throws
java.lang.IllegalStateException

If a MediaItem with an empty uri is passed as argument for a client-side inserted ad group.

withAvailableAdUri

fun withAvailableAdUri(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int,
    uri: Uri!
): AdPlaybackState!

withContentDurationUs

fun withContentDurationUs(contentDurationUs: Long): AdPlaybackState!

Returns an instance with the specified content duration, in microseconds.

withContentResumeOffsetUs

fun withContentResumeOffsetUs(
    adGroupIndex: @IntRange(from = 0) Int,
    contentResumeOffsetUs: Long
): AdPlaybackState!

Returns an instance with the specified contentResumeOffsetUs, in microseconds, for the specified ad group.

withIsServerSideInserted

fun withIsServerSideInserted(
    adGroupIndex: @IntRange(from = 0) Int,
    isServerSideInserted: Boolean
): AdPlaybackState!

Returns an instance with the specified value for isServerSideInserted in the specified ad group.

withLastAdRemoved

fun withLastAdRemoved(adGroupIndex: @IntRange(from = 0) Int): AdPlaybackState!

Returns an instance with the last ad of the given ad group removed.

withLivePostrollPlaceholderAppended

fun withLivePostrollPlaceholderAppended(): AdPlaybackState!

Appends a live postroll placeholder ad group to the ad playback state.

Adding such a placeholder is only required for periods of server side ad insertion live streams. A player is not expected to play this placeholder. It is only used to indicate that another ad group with this ad group index will be inserted in the future.

See endsWithLivePostrollPlaceHolder also.

Returns
AdPlaybackState!

The new ad playback state instance ending with a live postroll placeholder.

withNewAdGroup

fun withNewAdGroup(adGroupIndex: @IntRange(from = 0) Int, adGroupTimeUs: Long): AdPlaybackState!

Returns an instance with a new ad group.

Parameters
adGroupIndex: @IntRange(from = 0) Int

The insertion index of the new group.
adGroupTimeUs: Long

The ad group time, in microseconds, or TIME_END_OF_SOURCE to indicate a postroll ad.
Returns
AdPlaybackState!

The updated ad playback state.

withOriginalAdCount

fun withOriginalAdCount(
    adGroupIndex: @IntRange(from = 0) Int,
    originalAdCount: Int
): AdPlaybackState!

Returns an instance with the specified value for originalCount in the specified ad group.

withPlayedAd

fun withPlayedAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
): AdPlaybackState!

Returns an instance with the specified ad marked as played.

withRemovedAdGroupCount

fun withRemovedAdGroupCount(removedAdGroupCount: @IntRange(from = 0) Int): AdPlaybackState!

Returns an instance with the specified number of removed ad groups.

Ad groups with indices between 0 (inclusive) and removedAdGroupCount (exclusive) will be empty and must not be modified by any of the with* methods.

withResetAdGroup

fun withResetAdGroup(adGroupIndex: @IntRange(from = 0) Int): AdPlaybackState!

Returns an instance with all ads in the specified ad group reset from final states (played, skipped, error) to either available or unavailable, which allows to play them again.

withSkippedAd

fun withSkippedAd(
    adGroupIndex: @IntRange(from = 0) Int,
    adIndexInAdGroup: @IntRange(from = 0) Int
): AdPlaybackState!

Returns an instance with the specified ad marked as skipped.

withSkippedAdGroup

fun withSkippedAdGroup(adGroupIndex: @IntRange(from = 0) Int): AdPlaybackState!

Returns an instance with all ads in the specified ad group skipped (except for those already marked as played or in the error state).

Public properties

adGroupCount

val adGroupCount: Int

The number of ad groups.

adResumePositionUs

val adResumePositionUs: Long

The position offset in the first unplayed ad at which to begin playback, in microseconds.

adsId

val adsId: Any?

The opaque identifier for ads with which this instance is associated, or null if unset.

contentDurationUs

val contentDurationUs: Long

The duration of the content period in microseconds, if known. TIME_UNSET otherwise.

removedAdGroupCount

val removedAdGroupCount: Int

The number of ad groups that have been removed. Ad groups with indices between 0 (inclusive) and removedAdGroupCount (exclusive) will be empty and must not be modified by any of the with* methods.