mirror of
https://github.com/samsonjs/media.git
synced 2026-03-27 09:45:47 +00:00
Update window/period doc in Timeline.
Most users are likely to be only interested in the playlist items. So put the Window definition first and explicitly mention that this is a playlist item. PiperOrigin-RevId: 263764515
This commit is contained in:
tonihei
Toni
parent
9dd04baef6
commit
89dd105034
1 changed files with 68 additions and 72 deletions
|
|
@ -26,96 +26,92 @@ import com.google.android.exoplayer2.util.Assertions;
|
|||
* 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.
|
||||
* <p>
|
||||
* A timeline consists of related {@link Period}s and {@link Window}s. 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. A window
|
||||
* spans one or more periods, defining the region within those periods that's currently available
|
||||
* for playback along with additional information such as whether seeking is supported within the
|
||||
* window. Each window defines a default position, which is the position from which playback will
|
||||
* start when the player starts playing the window. The following examples illustrate timelines for
|
||||
* various use cases.
|
||||
*
|
||||
* <p>A timeline consists of {@link Window Windows} and {@link Period Periods}.
|
||||
*
|
||||
* <ul>
|
||||
* <li>A {@link 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.
|
||||
* <li>A {@link 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.
|
||||
* </ul>
|
||||
*
|
||||
* <p>The following examples illustrate timelines for various use cases.
|
||||
*
|
||||
* <h3 id="single-file">Single media file or on-demand stream</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-single-file.svg" alt="Example timeline for a single file">
|
||||
* </p>
|
||||
* 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).
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-single-file.svg" alt="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).
|
||||
*
|
||||
* <h3>Playlist of media files or on-demand streams</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-playlist.svg" alt="Example timeline for a playlist of files">
|
||||
* </p>
|
||||
* 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.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-playlist.svg" alt="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.
|
||||
*
|
||||
* <h3 id="live-limited">Live stream with limited availability</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-live-limited.svg" alt="Example timeline for a live stream with
|
||||
* limited availability">
|
||||
* </p>
|
||||
* 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 have {@link Window#isDynamic} set to true if
|
||||
* the stream is still live. Its default position is typically near to the live edge (indicated by
|
||||
* the black dot in the figure above).
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-live-limited.svg" alt="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 have {@link
|
||||
* Window#isDynamic} set to true if the stream is still live. Its default position is typically near
|
||||
* to the live edge (indicated by the black dot in the figure above).
|
||||
*
|
||||
* <h3>Live stream with indefinite availability</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-live-indefinite.svg" alt="Example timeline for a live stream with
|
||||
* indefinite availability">
|
||||
* </p>
|
||||
* A timeline for a live stream with indefinite availability is similar to the
|
||||
* <a href="#live-limited">Live stream with limited availability</a> 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.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-live-indefinite.svg" alt="Example timeline for a
|
||||
* live stream with indefinite availability"> A timeline for a live stream with indefinite
|
||||
* availability is similar to the <a href="#live-limited">Live stream with limited availability</a>
|
||||
* 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.
|
||||
*
|
||||
* <h3 id="live-multi-period">Live stream with multiple periods</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-live-multi-period.svg" alt="Example timeline for a live stream
|
||||
* with multiple periods">
|
||||
* </p>
|
||||
* This case arises when a live stream is explicitly divided into separate periods, for example at
|
||||
* content boundaries. This case is similar to the <a href="#live-limited">Live stream with limited
|
||||
* availability</a> case, except that the window may span more than one period. Multiple periods are
|
||||
* also possible in the indefinite availability case.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-live-multi-period.svg" alt="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 <a
|
||||
* href="#live-limited">Live stream with limited availability</a> case, except that the window may
|
||||
* span more than one period. Multiple periods are also possible in the indefinite availability
|
||||
* case.
|
||||
*
|
||||
* <h3>On-demand stream followed by live stream</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-advanced.svg" alt="Example timeline for an on-demand stream
|
||||
* followed by a live stream">
|
||||
* </p>
|
||||
* This case is the concatenation of the <a href="#single-file">Single media file or on-demand
|
||||
* stream</a> and <a href="#multi-period">Live stream with multiple periods</a> cases. When playback
|
||||
* of the on-demand stream ends, playback of the live stream will start from its default position
|
||||
* near the live edge.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-advanced.svg" alt="Example timeline for an
|
||||
* on-demand stream followed by a live stream"> This case is the concatenation of the <a
|
||||
* href="#single-file">Single media file or on-demand stream</a> and <a href="#multi-period">Live
|
||||
* stream with multiple periods</a> cases. When playback of the on-demand stream ends, playback of
|
||||
* the live stream will start from its default position near the live edge.
|
||||
*
|
||||
* <h3 id="single-file-midrolls">On-demand stream with mid-roll ads</h3>
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-single-file-midrolls.svg" alt="Example timeline for an on-demand
|
||||
* stream with mid-roll ad groups">
|
||||
* </p>
|
||||
* 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.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-single-file-midrolls.svg" alt="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.
|
||||
*/
|
||||
public abstract class Timeline {
|
||||
|
||||
/**
|
||||
* Holds information about a window in a {@link Timeline}. A window defines a region of media
|
||||
* currently available for playback along with additional information such as whether seeking is
|
||||
* supported within the window. The figure below shows some of the information defined by a
|
||||
* window, as well as how this information relates to corresponding {@link Period}s in the
|
||||
* timeline.
|
||||
* <p align="center">
|
||||
* <img src="doc-files/timeline-window.svg" alt="Information defined by a timeline window">
|
||||
* </p>
|
||||
* Holds information about a window in a {@link Timeline}. A window usually corresponds to one
|
||||
* playlist item and defines a region of media currently available for playback along with
|
||||
* additional information such as whether seeking is supported within the window. The figure below
|
||||
* shows some of the information defined by a window, as well as how this information relates to
|
||||
* corresponding {@link Period Periods} in the timeline.
|
||||
*
|
||||
* <p align="center"><img src="doc-files/timeline-window.svg" alt="Information defined by a
|
||||
* timeline window">
|
||||
*/
|
||||
public static final class Window {
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue