Timeline.Period

Artifact: androidx.media3:media3-common

View Source

---

Kotlin |Java

class Timeline.Period : Bundleable

---

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.

Summary

Constants
const Bundleable.Creator<Timeline.Period!>!	@UnstableApi CREATOR This property is deprecated. Use fromBundle instead.

Public constructors
Period() Creates a new instance with no ad playback state.

Public functions
Boolean	equals(obj: Any?)
java-static Timeline.Period!	@UnstableApi fromBundle(bundle: Bundle!) Restores a Period from a Bundle.
Int	getAdCountInAdGroup(adGroupIndex: Int) Returns the number of ads in the ad group at index adGroupIndex, or LENGTH_UNSET if not yet known.
Long	getAdDurationUs(adGroupIndex: Int, adIndexInAdGroup: Int) 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	getAdGroupCount() Returns the number of ad groups in the period.
Int	getAdGroupIndexAfterPositionUs(positionUs: Long) Returns the index of the next ad group after positionUs in the period that has ads that should be played.
Int	getAdGroupIndexForPositionUs(positionUs: Long) 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(adGroupIndex: Int) Returns the time of the ad group at index adGroupIndex in the period, in microseconds.
Long	getAdResumePositionUs() Returns the position offset in the first unplayed ad at which to begin playback, in microseconds.
Int	@UnstableApi getAdState(adGroupIndex: Int, adIndexInAdGroup: Int) Returns the state of the ad at index adIndexInAdGroup in the ad group at adGroupIndex, or AD_STATE_UNAVAILABLE if not yet known.
Any?	getAdsId() Returns the opaque identifier for ads played with this period, or null if unset.
Long	@UnstableApi getContentResumeOffsetUs(adGroupIndex: Int) Returns the offset in microseconds which should be added to the content stream when resuming playback after the specified ad group.
Long	getDurationMs() Returns the duration of the period in milliseconds, or TIME_UNSET if unknown.
Long	getDurationUs() Returns the duration of this period in microseconds, or TIME_UNSET if unknown.
Int	getFirstAdIndexToPlay(adGroupIndex: Int) 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(adGroupIndex: Int, lastPlayedAdIndex: Int) 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	getPositionInWindowMs() Returns the position of the start of this period relative to the start of the window to which it belongs, in milliseconds.
Long	getPositionInWindowUs() Returns the position of the start of this period relative to the start of the window to which it belongs, in microseconds.
Int	getRemovedAdGroupCount() Returns the number of removed ad groups in the period.
Boolean	hasPlayedAdGroup(adGroupIndex: Int) Returns whether all ads in the ad group at index adGroupIndex have been played, skipped or failed.
Int	hashCode()
Boolean	@UnstableApi isLivePostrollPlaceholder(adGroupIndex: Int) Returns whether the ad group at the given ad group index is a live postroll placeholder.
Boolean	@UnstableApi isServerSideInsertedAdGroup(adGroupIndex: Int) Returns whether the ad group at index adGroupIndex is server-side inserted and part of the content stream.
Timeline.Period!	@CanIgnoreReturnValue @UnstableApi set(     id: Any?,     uid: Any?,     windowIndex: Int,     durationUs: Long,     positionInWindowUs: Long ) Sets the data held by this period.
Timeline.Period!	@CanIgnoreReturnValue @UnstableApi set(     id: Any?,     uid: Any?,     windowIndex: Int,     durationUs: Long,     positionInWindowUs: Long,     adPlaybackState: AdPlaybackState!,     isPlaceholder: Boolean ) Sets the data held by this period.
Bundle!	@UnstableApi toBundle() Returns a representing the information stored in this object.

Public properties
Long	@UnstableApi durationUs The duration of this period in microseconds, or TIME_UNSET if unknown.
Any?	id An identifier for the period.
Boolean	isPlaceholder Whether this period contains placeholder information because the real information has yet to be loaded.
Long	@UnstableApi positionInWindowUs The position of the start of this period relative to the start of the window to which it belongs, in microseconds.
Any?	uid A unique identifier for the period.
Int	windowIndex The index of the window to which this period belongs.

Constants

CREATOR

@UnstableApi
const val CREATOR: Bundleable.Creator<Timeline.Period!>!

This property is deprecated.

Use fromBundle instead.

Object that can restore Period from a Bundle.

The id and uid of restored instances will always be null.

Public constructors

Period

Period()

Creates a new instance with no ad playback state.

Public functions

equals

fun equals(obj: Any?): Boolean

fromBundle

@UnstableApi
java-static fun fromBundle(bundle: Bundle!): Timeline.Period!

Restores a Period from a Bundle.

getAdCountInAdGroup

fun getAdCountInAdGroup(adGroupIndex: Int): Int

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

Parameters
adGroupIndex: Int	The ad group index.

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

getAdDurationUs

fun getAdDurationUs(adGroupIndex: Int, adIndexInAdGroup: Int): Long

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
adGroupIndex: Int	The ad group index.
adIndexInAdGroup: Int	The ad index in the ad group.

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

getAdGroupCount

fun getAdGroupCount(): Int

Returns the number of ad groups in the period.

getAdGroupIndexAfterPositionUs

fun getAdGroupIndexAfterPositionUs(positionUs: Long): Int

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
positionUs: Long	The period position after which to find an ad group, in microseconds.

Returns
Int	The index of the ad group, or INDEX_UNSET.

getAdGroupIndexForPositionUs

fun getAdGroupIndexForPositionUs(positionUs: Long): Int

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
positionUs: Long	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

fun getAdGroupTimeUs(adGroupIndex: Int): Long

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

Parameters
adGroupIndex: Int	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

fun getAdResumePositionUs(): Long

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

getAdState

@UnstableApi
fun getAdState(adGroupIndex: Int, adIndexInAdGroup: Int): Int

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

Parameters
adGroupIndex: Int	The ad group index.
adIndexInAdGroup: Int	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

fun getAdsId(): Any?

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

getContentResumeOffsetUs

@UnstableApi
fun getContentResumeOffsetUs(adGroupIndex: Int): Long

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

Parameters
adGroupIndex: Int	The ad group index.

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

getDurationMs

fun getDurationMs(): Long

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

getDurationUs

fun getDurationUs(): Long

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

getFirstAdIndexToPlay

fun getFirstAdIndexToPlay(adGroupIndex: Int): Int

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
adGroupIndex: Int	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

fun getNextAdIndexToPlay(adGroupIndex: Int, lastPlayedAdIndex: Int): Int

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
adGroupIndex: Int	The ad group index.
lastPlayedAdIndex: Int	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

fun getPositionInWindowMs(): Long

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

fun getPositionInWindowUs(): Long

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

fun getRemovedAdGroupCount(): Int

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

hasPlayedAdGroup

fun hasPlayedAdGroup(adGroupIndex: Int): Boolean

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

Parameters
adGroupIndex: Int	The ad group index.

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

hashCode

fun hashCode(): Int

isLivePostrollPlaceholder

@UnstableApi
fun isLivePostrollPlaceholder(adGroupIndex: Int): Boolean

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

isServerSideInsertedAdGroup

@UnstableApi
fun isServerSideInsertedAdGroup(adGroupIndex: Int): Boolean

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

Parameters
adGroupIndex: Int	The ad group index.

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

set

@CanIgnoreReturnValue
@UnstableApi
fun set(
    id: Any?,
    uid: Any?,
    windowIndex: Int,
    durationUs: Long,
    positionInWindowUs: Long
): Timeline.Period!

Sets the data held by this period.

Parameters
id: Any?	An identifier for the period. Not necessarily unique. May be null if the ids of the period are not required.
uid: Any?	A unique identifier for the period. May be null if the ids of the period are not required.
windowIndex: Int	The index of the window to which this period belongs.
durationUs: Long	The duration of this period in microseconds, or TIME_UNSET if unknown.
positionInWindowUs: Long	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
fun set(
    id: Any?,
    uid: Any?,
    windowIndex: Int,
    durationUs: Long,
    positionInWindowUs: Long,
    adPlaybackState: AdPlaybackState!,
    isPlaceholder: Boolean
): Timeline.Period!

Sets the data held by this period.

Parameters
id: Any?	An identifier for the period. Not necessarily unique. May be null if the ids of the period are not required.
uid: Any?	A unique identifier for the period. May be null if the ids of the period are not required.
windowIndex: Int	The index of the window to which this period belongs.
durationUs: Long	The duration of this period in microseconds, or TIME_UNSET if unknown.
positionInWindowUs: Long	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.
isPlaceholder: Boolean	Whether this period contains placeholder information because the real information has yet to be loaded.

Returns
Timeline.Period!	This period, for convenience.

toBundle

@UnstableApi
fun toBundle(): Bundle!

Returns a representing the information stored in this object.

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

Public properties

durationUs

@UnstableApi
val durationUs: Long

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

id

val id: Any?

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

isPlaceholder

val isPlaceholder: Boolean

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

positionInWindowUs

@UnstableApi
val positionInWindowUs: Long

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

val uid: Any?

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

windowIndex

val windowIndex: Int

The index of the window to which this period belongs.