Class AdPlaybackState

  • All Implemented Interfaces:
    Bundleable

    public final class AdPlaybackState
    extends Object
    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.

    • Field Detail

      • AD_STATE_UNAVAILABLE

        public static final int AD_STATE_UNAVAILABLE
        State for an ad that does not yet have a URL.
        See Also:
        Constant Field Values
      • AD_STATE_AVAILABLE

        public static final int AD_STATE_AVAILABLE
        State for an ad that has a URL but has not yet been played.
        See Also:
        Constant Field Values
      • AD_STATE_SKIPPED

        public static final int AD_STATE_SKIPPED
        State for an ad that was skipped.
        See Also:
        Constant Field Values
      • AD_STATE_PLAYED

        public static final int AD_STATE_PLAYED
        State for an ad that was played in full.
        See Also:
        Constant Field Values
      • AD_STATE_ERROR

        public static final int AD_STATE_ERROR
        State for an ad that could not be loaded.
        See Also:
        Constant Field Values
      • NONE

        public static final AdPlaybackState NONE
        Ad playback state with no ads.
      • adsId

        @Nullable
        public final Object adsId
        The opaque identifier for ads with which this instance is associated, or null if unset.
      • 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.
      • contentDurationUs

        public final long contentDurationUs
        The duration of the content period in microseconds, if known. C.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.
    • Constructor Detail

      • AdPlaybackState

        public AdPlaybackState​(Object adsId,
                               long... adGroupTimesUs)
        Creates a new ad playback state with the specified ad group times.
        Parameters:
        adsId - The opaque identifier for ads with which this instance is associated.
        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 C.TIME_END_OF_SOURCE indicates that there is a postroll ad.
    • Method Detail

      • 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 C.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 - The period position at or before which to find an ad group, in microseconds, or C.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 - The duration of the containing timeline period, in microseconds, or C.TIME_UNSET if not known.
        Returns:
        The index of the ad group, or C.INDEX_UNSET.
      • getAdGroupIndexAfterPositionUs

        public int getAdGroupIndexAfterPositionUs​(long positionUs,
                                                  long periodDurationUs)
        Returns the index of the next ad group after positionUs that should be played. Returns C.INDEX_UNSET if there is no such ad group.
        Parameters:
        positionUs - The period position after which to find an ad group, in microseconds, or C.TIME_END_OF_SOURCE for the end of the stream (in which case there can be no ad group after the position).
        periodDurationUs - The duration of the containing timeline period, in microseconds, or C.TIME_UNSET if not known.
        Returns:
        The index of the ad group, or C.INDEX_UNSET.
      • isAdInErrorState

        public boolean isAdInErrorState​(@IntRange(from=0L)
                                        int adGroupIndex,
                                        @IntRange(from=0L)
                                        int adIndexInAdGroup)
        Returns whether the specified ad has been marked as in AD_STATE_ERROR.
      • withAdGroupTimeUs

        @CheckResult
        public AdPlaybackState withAdGroupTimeUs​(@IntRange(from=0L)
                                                 int adGroupIndex,
                                                 long adGroupTimeUs)
        Returns an instance with the specified ad group time.
        Parameters:
        adGroupIndex - The index of the ad group.
        adGroupTimeUs - The new ad group time, in microseconds, or C.TIME_END_OF_SOURCE to indicate a postroll ad.
        Returns:
        The updated ad playback state.
      • withNewAdGroup

        @CheckResult
        public AdPlaybackState withNewAdGroup​(@IntRange(from=0L)
                                              int adGroupIndex,
                                              long adGroupTimeUs)
        Returns an instance with a new ad group.
        Parameters:
        adGroupIndex - The insertion index of the new group.
        adGroupTimeUs - The ad group time, in microseconds, or C.TIME_END_OF_SOURCE to indicate a postroll ad.
        Returns:
        The updated ad playback state.
      • withAdCount

        @CheckResult
        public AdPlaybackState withAdCount​(@IntRange(from=0L)
                                           int adGroupIndex,
                                           @IntRange(from=1L)
                                           int adCount)
        Returns an instance with the number of ads in adGroupIndex resolved to adCount. The ad count must be greater than zero.
      • withAvailableAdUri

        @CheckResult
        public AdPlaybackState withAvailableAdUri​(@IntRange(from=0L)
                                                  int adGroupIndex,
                                                  @IntRange(from=0L)
                                                  int adIndexInAdGroup,
                                                  Uri uri)
        Returns an instance with the specified ad URI and the ad marked as available.
        Throws:
        IllegalStateException - If Uri.EMPTY is passed as argument for a client-side inserted ad group.
      • withPlayedAd

        @CheckResult
        public AdPlaybackState withPlayedAd​(@IntRange(from=0L)
                                            int adGroupIndex,
                                            @IntRange(from=0L)
                                            int adIndexInAdGroup)
        Returns an instance with the specified ad marked as played.
      • withSkippedAd

        @CheckResult
        public AdPlaybackState withSkippedAd​(@IntRange(from=0L)
                                             int adGroupIndex,
                                             @IntRange(from=0L)
                                             int adIndexInAdGroup)
        Returns an instance with the specified ad marked as skipped.
      • withLastAdRemoved

        @CheckResult
        public AdPlaybackState withLastAdRemoved​(@IntRange(from=0L)
                                                 int adGroupIndex)
        Returns an instance with the last ad of the given ad group removed.
      • withAdLoadError

        @CheckResult
        public AdPlaybackState withAdLoadError​(@IntRange(from=0L)
                                               int adGroupIndex,
                                               @IntRange(from=0L)
                                               int adIndexInAdGroup)
        Returns an instance with the specified ad marked as having a load error.
      • withSkippedAdGroup

        @CheckResult
        public AdPlaybackState withSkippedAdGroup​(@IntRange(from=0L)
                                                  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).
      • withAdDurationsUs

        @CheckResult
        public AdPlaybackState withAdDurationsUs​(long[][] adDurationUs)
        Returns an instance with the specified ad durations, in microseconds.

        Must only be used if removedAdGroupCount is 0.

      • withAdDurationsUs

        @CheckResult
        public AdPlaybackState withAdDurationsUs​(@IntRange(from=0L)
                                                 int adGroupIndex,
                                                 long... adDurationsUs)
        Returns an instance with the specified ad durations, in microseconds, in the specified ad group.
      • withAdResumePositionUs

        @CheckResult
        public AdPlaybackState withAdResumePositionUs​(long adResumePositionUs)
        Returns an instance with the specified ad resume position, in microseconds, relative to the start of the current ad.
      • withContentDurationUs

        @CheckResult
        public AdPlaybackState withContentDurationUs​(long contentDurationUs)
        Returns an instance with the specified content duration, in microseconds.
      • withRemovedAdGroupCount

        @CheckResult
        public AdPlaybackState withRemovedAdGroupCount​(@IntRange(from=0L)
                                                       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

        @CheckResult
        public AdPlaybackState withResetAdGroup​(@IntRange(from=0L)
                                                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.
      • fromAdPlaybackState

        public static AdPlaybackState fromAdPlaybackState​(Object adsId,
                                                          AdPlaybackState adPlaybackState)
        Returns a copy of the ad playback state with the given ads ID.
        Parameters:
        adsId - The new ads ID.
        adPlaybackState - The ad playback state to copy.
        Returns:
        The new ad playback state.
      • equals

        public boolean equals​(@Nullable
                              Object o)
        Overrides:
        equals in class Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • toBundle

        public Bundle toBundle()
        Returns a Bundle representing the information stored in this object.

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

        Specified by:
        toBundle in interface Bundleable