Timeline.Period

public final class Timeline.Period

Holds information about a period in a Timeline. A period defines a single logical piece of media, for example a media file. It may also define groups of ads inserted into the media, along with information about whether those ads have been loaded and played.

The figure below shows some of the information defined by a period, as well as how this information relates to a corresponding Window in the timeline.

Information defined by a period

Summary

Public fields
AdPlaybackState

The AdPlaybackState for all ads in this period.
long

The duration of this period in microseconds, or TIME_UNSET if unknown.
@Nullable Object

An identifier for the period.
boolean

Whether this period contains placeholder information because the real information has yet to be loaded.
long

The position of the start of this period relative to the start of the window to which it belongs, in microseconds.
@Nullable Object

A unique identifier for the period.
int

The index of the window to which this period belongs.

Public constructors

Creates a new instance with no ad playback state.

Public methods
boolean
static Timeline.Period

Restores a Period from a Bundle.
int
getAdCountInAdGroup(int adGroupIndex)

Returns the number of ads in the ad group at index adGroupIndex, or LENGTH_UNSET if not yet known.
long
getAdDurationUs(int adGroupIndex, int adIndexInAdGroup)

Returns the duration of the ad at index adIndexInAdGroup in the ad group at adGroupIndex, in microseconds, or TIME_UNSET if not yet known.
int

Returns the number of ad groups in the period.
int

Returns the index of the next ad group after positionUs in the period that has ads that should be played.
int

Returns the index of the ad group at or before positionUs in the period that should be played before the content at positionUs.
long
getAdGroupTimeUs(int adGroupIndex)

Returns the time of the ad group at index adGroupIndex in the period, in microseconds.
long

Returns the position offset in the first unplayed ad at which to begin playback, in microseconds.
int
@UnstableApi
getAdState(int adGroupIndex, int adIndexInAdGroup)

Returns the state of the ad at index adIndexInAdGroup in the ad group at adGroupIndex, or AD_STATE_UNAVAILABLE if not yet known.
@Nullable Object

Returns the opaque identifier for ads played with this period, or null if unset.
long

Returns the offset in microseconds which should be added to the content stream when resuming playback after the specified ad group.
long

Returns the duration of the period in milliseconds, or TIME_UNSET if unknown.
long

Returns the duration of this period in microseconds, or TIME_UNSET if unknown.
int
getFirstAdIndexToPlay(int adGroupIndex)

Returns the index of the first ad in the specified ad group that should be played, or the number of ads in the ad group if no ads should be played.
int
getNextAdIndexToPlay(int adGroupIndex, int lastPlayedAdIndex)

Returns the index of the next ad in the specified ad group that should be played after playing adIndexInAdGroup, or the number of ads in the ad group if no later ads should be played.
long

Returns the position of the start of this period relative to the start of the window to which it belongs, in milliseconds.
long

Returns the position of the start of this period relative to the start of the window to which it belongs, in microseconds.
int

Returns the number of removed ad groups in the period.
boolean
hasPlayedAdGroup(int adGroupIndex)

Returns whether all ads in the ad group at index adGroupIndex have been played, skipped or failed.
int
boolean

Returns whether the ad group at the given ad group index is a live postroll placeholder.
boolean

Returns whether the ad group at index adGroupIndex is server-side inserted and part of the content stream.
Timeline.Period
@CanIgnoreReturnValue
@UnstableApi
set(
    @Nullable Object id,
    @Nullable Object uid,
    int windowIndex,
    long durationUs,
    long positionInWindowUs
)

Sets the data held by this period.
Timeline.Period
@CanIgnoreReturnValue
@UnstableApi
set(
    @Nullable Object id,
    @Nullable Object uid,
    int windowIndex,
    long durationUs,
    long positionInWindowUs,
    AdPlaybackState adPlaybackState,
    boolean isPlaceholder
)

Sets the data held by this period.
Bundle

Returns a Bundle representing the information stored in this object.

Public fields

adPlaybackState

@UnstableApi
public AdPlaybackState adPlaybackState

The AdPlaybackState for all ads in this period.

durationUs

@UnstableApi
public long durationUs

The duration of this period in microseconds, or TIME_UNSET if unknown.

id

public @Nullable Object id

An identifier for the period. Not necessarily unique. May be null if the ids of the period are not required.

isPlaceholder

public boolean isPlaceholder

Whether this period contains placeholder information because the real information has yet to be loaded.

positionInWindowUs

@UnstableApi
public long positionInWindowUs

The position of the start of this period relative to the start of the window to which it belongs, in microseconds. May be negative if the start of the period is not within the window.

uid

public @Nullable Object uid

A unique identifier for the period. May be null if the ids of the period are not required.

windowIndex

public int windowIndex

The index of the window to which this period belongs.

Public constructors

Period

public Period()

Creates a new instance with no ad playback state.

Public methods

equals

public boolean equals(@Nullable Object obj)

fromBundle

@UnstableApi
public static Timeline.Period fromBundle(Bundle bundle)

Restores a Period from a Bundle.

getAdCountInAdGroup

public int getAdCountInAdGroup(int adGroupIndex)

Returns the number of ads in the ad group at index adGroupIndex, or LENGTH_UNSET if not yet known.

Parameters
int adGroupIndex

The ad group index.
Returns
int

The number of ads in the ad group, or LENGTH_UNSET if not yet known.

getAdDurationUs

public long getAdDurationUs(int adGroupIndex, int adIndexInAdGroup)

Returns the duration of the ad at index adIndexInAdGroup in the ad group at adGroupIndex, in microseconds, or TIME_UNSET if not yet known.

Parameters
int adGroupIndex

The ad group index.
int adIndexInAdGroup

The ad index in the ad group.
Returns
long

The duration of the ad, or TIME_UNSET if not yet known.

getAdGroupCount

public int getAdGroupCount()

Returns the number of ad groups in the period.

getAdGroupIndexAfterPositionUs

public int getAdGroupIndexAfterPositionUs(long positionUs)

Returns the index of the next ad group after positionUs in the period that has ads 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.
Returns
int

The index of the ad group, or INDEX_UNSET.

getAdGroupIndexForPositionUs

public int getAdGroupIndexForPositionUs(long positionUs)

Returns the index of the ad group at or before positionUs in the period 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.
Returns
int

The index of the ad group, or INDEX_UNSET.

getAdGroupTimeUs

public long getAdGroupTimeUs(int adGroupIndex)

Returns the time of the ad group at index adGroupIndex in the period, in microseconds.

Parameters
int adGroupIndex

The ad group index.
Returns
long

The time of the ad group at the index relative to the start of the enclosing , in microseconds, or TIME_END_OF_SOURCE for a post-roll ad group.

getAdResumePositionUs

public long getAdResumePositionUs()

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

getAdState

@UnstableApi
public int getAdState(int adGroupIndex, int adIndexInAdGroup)

Returns the state of the ad at index adIndexInAdGroup in the ad group at adGroupIndex, or AD_STATE_UNAVAILABLE if not yet known.

Parameters
int adGroupIndex

The ad group index.
int adIndexInAdGroup

The index of the ad in the ad group.
Returns
int

The state of the ad, or AD_STATE_UNAVAILABLE if not yet known.

getAdsId

public @Nullable Object getAdsId()

Returns the opaque identifier for ads played with this period, or null if unset.

getContentResumeOffsetUs

@UnstableApi
public long getContentResumeOffsetUs(int adGroupIndex)

Returns the offset in microseconds which should be added to the content stream when resuming playback after the specified ad group.

Parameters
int adGroupIndex

The ad group index.
Returns
long

The offset that should be added to the content stream, in microseconds.

getDurationMs

public long getDurationMs()

Returns the duration of the period in milliseconds, or TIME_UNSET if unknown.

getDurationUs

public long getDurationUs()

Returns the duration of this period in microseconds, or TIME_UNSET if unknown.

getFirstAdIndexToPlay

public int getFirstAdIndexToPlay(int adGroupIndex)

Returns the index of the first ad in the specified ad group that should be played, or the number of ads in the ad group if no ads should be played.

Parameters
int adGroupIndex

The ad group index.
Returns
int

The index of the first ad that should be played, or the number of ads in the ad group if no ads should be played.

getNextAdIndexToPlay

public int getNextAdIndexToPlay(int adGroupIndex, int lastPlayedAdIndex)

Returns the index of the next ad in the specified ad group that should be played after playing adIndexInAdGroup, or the number of ads in the ad group if no later ads should be played.

Parameters
int adGroupIndex

The ad group index.
int lastPlayedAdIndex

The last played ad index in the ad group.
Returns
int

The index of the next ad that should be played, or the number of ads in the ad group if the ad group does not have any ads remaining to play.

getPositionInWindowMs

public long getPositionInWindowMs()

Returns the position of the start of this period relative to the start of the window to which it belongs, in milliseconds. May be negative if the start of the period is not within the window.

getPositionInWindowUs

public long getPositionInWindowUs()

Returns the position of the start of this period relative to the start of the window to which it belongs, in microseconds. May be negative if the start of the period is not within the window.

getRemovedAdGroupCount

public int getRemovedAdGroupCount()

Returns the number of removed ad groups in the period. Ad groups with indices between 0 (inclusive) and removedAdGroupCount (exclusive) will be empty.

hasPlayedAdGroup

public boolean hasPlayedAdGroup(int adGroupIndex)

Returns whether all ads in the ad group at index adGroupIndex have been played, skipped or failed.

Parameters
int adGroupIndex

The ad group index.
Returns
boolean

Whether all ads in the ad group at index adGroupIndex have been played, skipped or failed.

hashCode

public int hashCode()

isLivePostrollPlaceholder

@UnstableApi
public boolean isLivePostrollPlaceholder(int adGroupIndex)

Returns whether the ad group 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.

isServerSideInsertedAdGroup

@UnstableApi
public boolean isServerSideInsertedAdGroup(int adGroupIndex)

Returns whether the ad group at index adGroupIndex is server-side inserted and part of the content stream.

Parameters
int adGroupIndex

The ad group index.
Returns
boolean

Whether this ad group is server-side inserted and part of the content stream.

set

@CanIgnoreReturnValue
@UnstableApi
public Timeline.Period set(
    @Nullable Object id,
    @Nullable Object uid,
    int windowIndex,
    long durationUs,
    long positionInWindowUs
)

Sets the data held by this period.

Parameters
@Nullable Object id

An identifier for the period. Not necessarily unique. May be null if the ids of the period are not required.
@Nullable Object uid

A unique identifier for the period. May be null if the ids of the period are not required.
int windowIndex

The index of the window to which this period belongs.
long durationUs

The duration of this period in microseconds, or TIME_UNSET if unknown.
long positionInWindowUs

The position of the start of this period relative to the start of the window to which it belongs, in milliseconds. May be negative if the start of the period is not within the window.
Returns
Timeline.Period

This period, for convenience.

set

@CanIgnoreReturnValue
@UnstableApi
public Timeline.Period set(
    @Nullable Object id,
    @Nullable Object uid,
    int windowIndex,
    long durationUs,
    long positionInWindowUs,
    AdPlaybackState adPlaybackState,
    boolean isPlaceholder
)

Sets the data held by this period.

Parameters
@Nullable Object id

An identifier for the period. Not necessarily unique. May be null if the ids of the period are not required.
@Nullable Object uid

A unique identifier for the period. May be null if the ids of the period are not required.
int windowIndex

The index of the window to which this period belongs.
long durationUs

The duration of this period in microseconds, or TIME_UNSET if unknown.
long positionInWindowUs

The position of the start of this period relative to the start of the window to which it belongs, in milliseconds. May be negative if the start of the period is not within the window.
AdPlaybackState adPlaybackState

The state of the period's ads, or NONE if there are no ads.
boolean isPlaceholder

Whether this period contains placeholder information because the real information has yet to be loaded.
Returns
Timeline.Period

This period, for convenience.

toBundle

@UnstableApi
public Bundle toBundle()

Returns a Bundle representing the information stored in this object.

It omits the id and uid fields so these fields of an instance restored by fromBundle will always be null.