AdPlaybackState

@UnstableApi
public final class AdPlaybackState implements Bundleable

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
public final class AdPlaybackState.AdGroup implements Bundleable

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

Represents the state of an ad in an ad group.

Constants
static final int

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

State for an ad that could not be loaded.
static final int

State for an ad that was played in full.
static final int

State for an ad that was skipped.
static final int

State for an ad that does not yet have a URL.
static final Bundleable.Creator<AdPlaybackState>

This field is deprecated.

Use fromBundle instead.
static final AdPlaybackState

Ad playback state with no ads.

Public fields
final int

The number of ad groups.
final long

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

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

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

The number of ad groups that have been removed.

Public constructors
AdPlaybackState(Object adsId, long[] adGroupTimesUs)

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

Public methods
boolean

Returns whether the last ad group is a live postroll placeholder as inserted by withLivePostrollPlaceholderAppended.
boolean
static AdPlaybackState
fromAdPlaybackState(Object adsId, AdPlaybackState adPlaybackState)

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

Restores a AdPlaybackState from a Bundle.
AdPlaybackState.AdGroup
getAdGroup(@IntRange(from = 0) int adGroupIndex)

Returns the specified AdGroup.
int
getAdGroupIndexAfterPositionUs(long positionUs, long periodDurationUs)

Returns the index of the next ad group after positionUs that should be played.
int
getAdGroupIndexForPositionUs(long positionUs, long periodDurationUs)

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

Returns whether the specified ad has been marked as in AD_STATE_ERROR.
boolean
isLivePostrollPlaceholder(int adGroupIndex)

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

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

Returns an instance with the number of ads in adGroupIndex resolved to adCount.
AdPlaybackState
withAdDurationsUs(long[][] adDurationUs)

Returns an instance with the specified ad durations, in microseconds.
AdPlaybackState
withAdDurationsUs(
    @IntRange(from = 0) int adGroupIndex,
    long[] adDurationsUs
)

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

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

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

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

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

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

This method is deprecated.

Use withAvailableAdMediaItem instead.
AdPlaybackState
withContentDurationUs(long contentDurationUs)

Returns an instance with the specified content duration, in microseconds.
AdPlaybackState
withContentResumeOffsetUs(
    @IntRange(from = 0) int adGroupIndex,
    long contentResumeOffsetUs
)

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

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

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(@IntRange(from = 0) int adGroupIndex, long adGroupTimeUs)

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

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

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

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

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(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

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

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

Constants

AD_STATE_AVAILABLE

public static final int AD_STATE_AVAILABLE = 1

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

AD_STATE_ERROR

public static final int AD_STATE_ERROR = 4

State for an ad that could not be loaded.

AD_STATE_PLAYED

public static final int AD_STATE_PLAYED = 3

State for an ad that was played in full.

AD_STATE_SKIPPED

public static final int AD_STATE_SKIPPED = 2

State for an ad that was skipped.

AD_STATE_UNAVAILABLE

public static final int AD_STATE_UNAVAILABLE = 0

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

CREATOR

public static final Bundleable.Creator<AdPlaybackState> CREATOR

Object that can restore AdPlaybackState from a Bundle.

The adsId of restored instances will always be null.

NONE

public static final AdPlaybackState NONE

Ad playback state with no ads.

Public fields

adGroupCount

public final int adGroupCount

The number of ad groups.

adResumePositionUs

public final long adResumePositionUs

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

adsId

public final @Nullable Object adsId

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

contentDurationUs

public final long contentDurationUs

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

removedAdGroupCount

public final int removedAdGroupCount

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.

Public constructors

AdPlaybackState

public AdPlaybackState(Object adsId, long[] adGroupTimesUs)

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

Parameters
Object adsId

The opaque identifier for ads with which this instance is associated.
long[] adGroupTimesUs

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 methods

endsWithLivePostrollPlaceHolder

public boolean endsWithLivePostrollPlaceHolder()

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

public boolean equals(@Nullable Object o)

fromAdPlaybackState

public static AdPlaybackState fromAdPlaybackState(Object adsId, AdPlaybackState adPlaybackState)

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

Parameters
Object adsId

The new ads ID.
AdPlaybackState adPlaybackState

The ad playback state to copy.
Returns
AdPlaybackState

The new ad playback state.

fromBundle

public static AdPlaybackState fromBundle(Bundle bundle)

Restores a AdPlaybackState from a Bundle.

getAdGroup

public AdPlaybackState.AdGroup getAdGroup(@IntRange(from = 0) int adGroupIndex)

Returns the specified AdGroup.

getAdGroupIndexAfterPositionUs

public int getAdGroupIndexAfterPositionUs(long positionUs, long periodDurationUs)

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
long positionUs

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).
long periodDurationUs

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

public int getAdGroupIndexForPositionUs(long positionUs, long periodDurationUs)

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
long positionUs

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).
long periodDurationUs

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

public int hashCode()

isAdInErrorState

public boolean isAdInErrorState(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

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

isLivePostrollPlaceholder

public boolean isLivePostrollPlaceholder(int adGroupIndex)

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

Parameters
int adGroupIndex

The ad group index.
Returns
boolean

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

toBundle

public Bundle toBundle()

Returns a representing the information stored in this object.

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

toString

public String toString()

withAdCount

public AdPlaybackState withAdCount(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 1) int adCount
)

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

withAdDurationsUs

public AdPlaybackState withAdDurationsUs(long[][] adDurationUs)

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

Must only be used if removedAdGroupCount is 0.

withAdDurationsUs

public AdPlaybackState withAdDurationsUs(
    @IntRange(from = 0) int adGroupIndex,
    long[] adDurationsUs
)

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

withAdGroupTimeUs

public AdPlaybackState withAdGroupTimeUs(@IntRange(from = 0) int adGroupIndex, long adGroupTimeUs)

Returns an instance with the specified ad group time.

Parameters
@IntRange(from = 0) int adGroupIndex

The index of the ad group.
long adGroupTimeUs

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

public AdPlaybackState withAdLoadError(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

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

withAdResumePositionUs

public AdPlaybackState withAdResumePositionUs(long adResumePositionUs)

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

withAvailableAd

public AdPlaybackState withAvailableAd(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

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

public AdPlaybackState withAvailableAdMediaItem(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup,
    MediaItem mediaItem
)

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

public AdPlaybackState withAvailableAdUri(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup,
    Uri uri
)

withContentDurationUs

public AdPlaybackState withContentDurationUs(long contentDurationUs)

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

withContentResumeOffsetUs

public AdPlaybackState withContentResumeOffsetUs(
    @IntRange(from = 0) int adGroupIndex,
    long contentResumeOffsetUs
)

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

withIsServerSideInserted

public AdPlaybackState withIsServerSideInserted(
    @IntRange(from = 0) int adGroupIndex,
    boolean isServerSideInserted
)

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

withLastAdRemoved

public AdPlaybackState withLastAdRemoved(@IntRange(from = 0) int adGroupIndex)

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

withLivePostrollPlaceholderAppended

public AdPlaybackState withLivePostrollPlaceholderAppended()

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

public AdPlaybackState withNewAdGroup(@IntRange(from = 0) int adGroupIndex, long adGroupTimeUs)

Returns an instance with a new ad group.

Parameters
@IntRange(from = 0) int adGroupIndex

The insertion index of the new group.
long adGroupTimeUs

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

The updated ad playback state.

withOriginalAdCount

public AdPlaybackState withOriginalAdCount(
    @IntRange(from = 0) int adGroupIndex,
    int originalAdCount
)

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

withPlayedAd

public AdPlaybackState withPlayedAd(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

Returns an instance with the specified ad marked as played.

withRemovedAdGroupCount

public AdPlaybackState withRemovedAdGroupCount(@IntRange(from = 0) int removedAdGroupCount)

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

public AdPlaybackState withResetAdGroup(@IntRange(from = 0) int adGroupIndex)

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

public AdPlaybackState withSkippedAd(
    @IntRange(from = 0) int adGroupIndex,
    @IntRange(from = 0) int adIndexInAdGroup
)

Returns an instance with the specified ad marked as skipped.

withSkippedAdGroup

public AdPlaybackState withSkippedAdGroup(@IntRange(from = 0) int adGroupIndex)

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