abstract class Timeline

Known direct subclasses
AbstractConcatenatedTimeline

Abstract base class for the concatenation of one or more Timelines.
FakeMultiPeriodLiveTimeline

A fake Timeline that produces a live window with periods according to the available time range.
FakeTimeline

Fake Timeline which can be setup to return custom TimelineWindowDefinitions.
ForwardingTimeline

An overridable Timeline implementation forwarding all methods to another timeline.
MaskingMediaSource.PlaceholderTimeline

A timeline with one dynamic window with a period of indeterminate duration.
SinglePeriodTimeline

A Timeline consisting of a single period and static window.
Timeline.RemotableTimeline

A concrete class of Timeline to restore a Timeline instance from a sent by another process via IBinder.
Known indirect subclasses
FakeMediaSource.InitialTimeline

A forwarding timeline to provide an initial timeline for fake multi window sources.
SinglePeriodAdTimeline

A Timeline for sources that have ads.
TimelineWithUpdatedMediaItem

A Timeline that overrides the MediaItem.

A flexible representation of the structure of media. A timeline is able to represent the structure of a wide variety of media, from simple cases like a single media file through to complex compositions of media such as playlists and streams with inserted ads. Instances are immutable. For cases where media is changing dynamically (e.g. live streams), a timeline provides a snapshot of the current state.

A timeline consists of Windows and Periods.

  • A Window usually corresponds to one playlist item. It may span one or more periods and it defines the region within those periods that's currently available for playback. The window also provides additional information such as whether seeking is supported within the window and the default position, which is the position from which playback will start when the player starts playing the window.
  • 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 following examples illustrate timelines for various use cases.

Single media file or on-demand stream

Example timeline for a single file

A timeline for a single media file or on-demand stream consists of a single period and window. The window spans the whole period, indicating that all parts of the media are available for playback. The window's default position is typically at the start of the period (indicated by the black dot in the figure above).

Playlist of media files or on-demand streams

Example timeline for a playlist of files

A timeline for a playlist of media files or on-demand streams consists of multiple periods, each with its own window. Each window spans the whole of the corresponding period, and typically has a default position at the start of the period. The properties of the periods and windows (e.g. their durations and whether the window is seekable) will often only become known when the player starts buffering the corresponding file or stream.

Live stream with limited availability

Example timeline for a live stream with limited availability

A timeline for a live stream consists of a period whose duration is unknown, since it's continually extending as more content is broadcast. If content only remains available for a limited period of time then the window may start at a non-zero position, defining the region of content that can still be played. The window will return true from isLive to indicate it's a live stream and isDynamic will be set to true as long as we expect changes to the live window. Its default position is typically near to the live edge (indicated by the black dot in the figure above).

Live stream with indefinite availability

Example timeline for a live stream with indefinite availability

A timeline for a live stream with indefinite availability is similar to the Live stream with limited availability case, except that the window starts at the beginning of the period to indicate that all of the previously broadcast content can still be played.

Live stream with multiple periods

Example timeline for a live stream with multiple periods

This case arises when a live stream is explicitly divided into separate periods, for example at content boundaries. This case is similar to the Live stream with limited availability case, except that the window may span more than one period. Multiple periods are also possible in the indefinite availability case.

On-demand stream followed by live stream

Example timeline for an on-demand stream followed by a live stream

This case is the concatenation of the Single media file or on-demand stream and Live stream with multiple periods cases. When playback of the on-demand stream ends, playback of the live stream will start from its default position near the live edge.

On-demand stream with mid-roll ads

Example timeline for an on-demand stream with mid-roll ad groups

This case includes mid-roll ad groups, which are defined as part of the timeline's single period. The period can be queried for information about the ad groups and the ads they contain.

Summary

Nested types

Holds information about a period in a Timeline.

A concrete class of Timeline to restore a Timeline instance from a sent by another process via IBinder.

Holds information about a window in a Timeline.

Constants
const Timeline!

An empty timeline.

Protected constructors

Public functions
Timeline!

Returns a copy of this timeline containing just the single specified Window.
Boolean
equals(obj: Any?)
java-static Timeline!

Restores a Timeline from a Bundle.
Int
getFirstWindowIndex(shuffleModeEnabled: Boolean)

Returns the index of the first window in the playback order depending on whether shuffling is enabled.
abstract Int

Returns the index of the period identified by its unique uid, or INDEX_UNSET if the period is not in the timeline.
Int
getLastWindowIndex(shuffleModeEnabled: Boolean)

Returns the index of the last window in the playback order depending on whether shuffling is enabled.
Int
getNextPeriodIndex(
    periodIndex: Int,
    period: Timeline.Period!,
    window: Timeline.Window!,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
)

Returns the index of the period after the period at index periodIndex depending on the repeatMode and whether shuffling is enabled.
Int
getNextWindowIndex(
    windowIndex: Int,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
)

Returns the index of the window after the window at index windowIndex depending on the repeatMode and whether shuffling is enabled.
Timeline.Period!
getPeriod(periodIndex: Int, period: Timeline.Period!)

Populates a Period with data for the period at the specified index.
abstract Timeline.Period!
getPeriod(periodIndex: Int, period: Timeline.Period!, setIds: Boolean)

Populates a Period with data for the period at the specified index.
Timeline.Period!
getPeriodByUid(periodUid: Any!, period: Timeline.Period!)

Populates a Period with data for the period with the specified unique identifier.
abstract Int

Returns the number of periods in the timeline.
Pair<Any!, Long!>!
@UnstableApi
@InlineMe(replacement = "this.getPeriodPositionUs(window, period, windowIndex, windowPositionUs)")
getPeriodPosition(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long
)

This function is deprecated.

Use getPeriodPositionUs instead.
Pair<Any!, Long!>?
@UnstableApi
@InlineMe(replacement = "this.getPeriodPositionUs(" + "window, period, windowIndex, windowPositionUs, defaultPositionProjectionUs)")
getPeriodPosition(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long,
    defaultPositionProjectionUs: Long
)

This function is deprecated.

Use getPeriodPositionUs instead.
Pair<Any!, Long!>!
getPeriodPositionUs(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long
)

Calls getPeriodPositionUs with a zero default position projection.
Pair<Any!, Long!>?
getPeriodPositionUs(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long,
    defaultPositionProjectionUs: Long
)

Converts (windowIndex, windowPositionUs) to the corresponding (periodUid, periodPositionUs).
Int
getPreviousWindowIndex(
    windowIndex: Int,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
)

Returns the index of the window before the window at index windowIndex depending on the repeatMode and whether shuffling is enabled.
abstract Any!
getUidOfPeriod(periodIndex: Int)

Returns the unique id of the period identified by its index in the timeline.
Timeline.Window!
getWindow(windowIndex: Int, window: Timeline.Window!)

Populates a Window with data for the window at the specified index.
abstract Timeline.Window!
getWindow(
    windowIndex: Int,
    window: Timeline.Window!,
    defaultPositionProjectionUs: Long
)

Populates a Window with data for the window at the specified index.
abstract Int

Returns the number of windows in the timeline.
Int
Boolean

Returns whether the timeline is empty.
Boolean
isLastPeriod(
    periodIndex: Int,
    period: Timeline.Period!,
    window: Timeline.Window!,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
)

Returns whether the given period is the last period of the timeline depending on the repeatMode and whether shuffling is enabled.
Bundle!

Returns a Bundle representing the information stored in this object.

Constants

EMPTY

const val EMPTY: Timeline!

An empty timeline.

Protected constructors

Timeline

@UnstableApi
protected Timeline()

Public functions

copyWithSingleWindow

@UnstableApi
fun copyWithSingleWindow(windowIndex: Int): Timeline!

Returns a copy of this timeline containing just the single specified Window.

The method returns the same instance if there is only one window.

Parameters
windowIndex: Int

The index of the Window to include in the copy.
Returns
Timeline!

A Timeline with just the single specified Window.

equals

fun equals(obj: Any?): Boolean

fromBundle

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

Restores a Timeline from a Bundle.

getFirstWindowIndex

fun getFirstWindowIndex(shuffleModeEnabled: Boolean): Int

Returns the index of the first window in the playback order depending on whether shuffling is enabled.

Parameters
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Int

The index of the first window in the playback order, or INDEX_UNSET if the timeline is empty.

getIndexOfPeriod

abstract fun getIndexOfPeriod(uid: Any!): Int

Returns the index of the period identified by its unique uid, or INDEX_UNSET if the period is not in the timeline.

Parameters
uid: Any!

A unique identifier for a period.
Returns
Int

The index of the period, or INDEX_UNSET if the period was not found.

getLastWindowIndex

fun getLastWindowIndex(shuffleModeEnabled: Boolean): Int

Returns the index of the last window in the playback order depending on whether shuffling is enabled.

Parameters
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Int

The index of the last window in the playback order, or INDEX_UNSET if the timeline is empty.

getNextPeriodIndex

fun getNextPeriodIndex(
    periodIndex: Int,
    period: Timeline.Period!,
    window: Timeline.Window!,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
): Int

Returns the index of the period after the period at index periodIndex depending on the repeatMode and whether shuffling is enabled.

Parameters
periodIndex: Int

Index of a period in the timeline.
period: Timeline.Period!

A Period to be used internally. Must not be null.
window: Timeline.Window!

A Window to be used internally. Must not be null.
@Player.RepeatMode repeatMode: Int

A repeat mode.
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Int

The index of the next period, or INDEX_UNSET if this is the last period.

getNextWindowIndex

fun getNextWindowIndex(
    windowIndex: Int,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
): Int

Returns the index of the window after the window at index windowIndex depending on the repeatMode and whether shuffling is enabled.

Parameters
windowIndex: Int

Index of a window in the timeline.
@Player.RepeatMode repeatMode: Int

A repeat mode.
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Int

The index of the next window, or INDEX_UNSET if this is the last window.

getPeriod

fun getPeriod(periodIndex: Int, period: Timeline.Period!): Timeline.Period!

Populates a Period with data for the period at the specified index. id and uid will be set to null.

Parameters
periodIndex: Int

The index of the period.
period: Timeline.Period!

The Period to populate. Must not be null.
Returns
Timeline.Period!

The populated Period, for convenience.

getPeriod

abstract fun getPeriod(periodIndex: Int, period: Timeline.Period!, setIds: Boolean): Timeline.Period!

Populates a Period with data for the period at the specified index.

Parameters
periodIndex: Int

The index of the period.
period: Timeline.Period!

The Period to populate. Must not be null.
setIds: Boolean

Whether id and uid should be populated. If false, the fields will be set to null. The caller should pass false for efficiency reasons unless the fields are required.
Returns
Timeline.Period!

The populated Period, for convenience.

getPeriodByUid

fun getPeriodByUid(periodUid: Any!, period: Timeline.Period!): Timeline.Period!

Populates a Period with data for the period with the specified unique identifier.

Parameters
periodUid: Any!

The unique identifier of the period.
period: Timeline.Period!

The Period to populate. Must not be null.
Returns
Timeline.Period!

The populated Period, for convenience.

getPeriodCount

abstract fun getPeriodCount(): Int

Returns the number of periods in the timeline.

getPeriodPosition

@UnstableApi
@InlineMe(replacement = "this.getPeriodPositionUs(window, period, windowIndex, windowPositionUs)")
fun getPeriodPosition(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long
): Pair<Any!, Long!>!

getPeriodPosition

@UnstableApi
@InlineMe(replacement = "this.getPeriodPositionUs("
              + "window, period, windowIndex, windowPositionUs, defaultPositionProjectionUs)")
fun getPeriodPosition(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long,
    defaultPositionProjectionUs: Long
): Pair<Any!, Long!>?

getPeriodPositionUs

fun getPeriodPositionUs(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long
): Pair<Any!, Long!>!

Calls getPeriodPositionUs with a zero default position projection.

getPeriodPositionUs

fun getPeriodPositionUs(
    window: Timeline.Window!,
    period: Timeline.Period!,
    windowIndex: Int,
    windowPositionUs: Long,
    defaultPositionProjectionUs: Long
): Pair<Any!, Long!>?

Converts (windowIndex, windowPositionUs) to the corresponding (periodUid, periodPositionUs). The returned periodPositionUs is constrained to be non-negative, and to be less than the containing period's duration if it is known.

Parameters
window: Timeline.Window!

A Window that may be overwritten.
period: Timeline.Period!

A Period that may be overwritten.
windowIndex: Int

The window index.
windowPositionUs: Long

The window time, or TIME_UNSET to use the window's default start position.
defaultPositionProjectionUs: Long

If windowPositionUs is TIME_UNSET, the duration into the future by which the window's position should be projected.
Returns
Pair<Any!, Long!>?

The corresponding (periodUid, periodPositionUs), or null if #windowPositionUs is TIME_UNSET, defaultPositionProjectionUs is non-zero, and the window's position could not be projected by defaultPositionProjectionUs.

getPreviousWindowIndex

fun getPreviousWindowIndex(
    windowIndex: Int,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
): Int

Returns the index of the window before the window at index windowIndex depending on the repeatMode and whether shuffling is enabled.

Parameters
windowIndex: Int

Index of a window in the timeline.
@Player.RepeatMode repeatMode: Int

A repeat mode.
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Int

The index of the previous window, or INDEX_UNSET if this is the first window.

getUidOfPeriod

abstract fun getUidOfPeriod(periodIndex: Int): Any!

Returns the unique id of the period identified by its index in the timeline.

Parameters
periodIndex: Int

The index of the period.
Returns
Any!

The unique id of the period.

getWindow

fun getWindow(windowIndex: Int, window: Timeline.Window!): Timeline.Window!

Populates a Window with data for the window at the specified index.

Parameters
windowIndex: Int

The index of the window.
window: Timeline.Window!

The Window to populate. Must not be null.
Returns
Timeline.Window!

The populated Window, for convenience.

getWindow

abstract fun getWindow(
    windowIndex: Int,
    window: Timeline.Window!,
    defaultPositionProjectionUs: Long
): Timeline.Window!

Populates a Window with data for the window at the specified index.

Parameters
windowIndex: Int

The index of the window.
window: Timeline.Window!

The Window to populate. Must not be null.
defaultPositionProjectionUs: Long

A duration into the future that the populated window's default start position should be projected.
Returns
Timeline.Window!

The populated Window, for convenience.

getWindowCount

abstract fun getWindowCount(): Int

Returns the number of windows in the timeline.

hashCode

fun hashCode(): Int

isEmpty

fun isEmpty(): Boolean

Returns whether the timeline is empty.

isLastPeriod

fun isLastPeriod(
    periodIndex: Int,
    period: Timeline.Period!,
    window: Timeline.Window!,
    @Player.RepeatMode repeatMode: Int,
    shuffleModeEnabled: Boolean
): Boolean

Returns whether the given period is the last period of the timeline depending on the repeatMode and whether shuffling is enabled.

Parameters
periodIndex: Int

A period index.
period: Timeline.Period!

A Period to be used internally. Must not be null.
window: Timeline.Window!

A Window to be used internally. Must not be null.
@Player.RepeatMode repeatMode: Int

A repeat mode.
shuffleModeEnabled: Boolean

Whether shuffling is enabled.
Returns
Boolean

Whether the period of the given index is the last period of the timeline.

toBundle

@UnstableApi
fun toBundle(): Bundle!

Returns a Bundle representing the information stored in this object.

The getWindow windows} and periods of an instance restored by fromBundle may have missing fields as described in toBundle and toBundle.