From 54e869cbbdf3bc5abbc08a090839e288e6624945 Mon Sep 17 00:00:00 2001 From: olly Date: Thu, 20 Jul 2017 04:51:59 -0700 Subject: [PATCH] Update Timeline Javadoc to include brief mention of ad groups ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=162601778 --- .../google/android/exoplayer2/Timeline.java | 57 ++++++++++++------- .../timeline-single-file-midrolls.svg | 51 +++++++++++++++++ 2 files changed, 86 insertions(+), 22 deletions(-) create mode 100644 library/core/src/main/javadoc/com/google/android/exoplayer2/doc-files/timeline-single-file-midrolls.svg diff --git a/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java b/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java index 60650f9990..e45171fc69 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/Timeline.java @@ -19,17 +19,20 @@ import android.util.Pair; import com.google.android.exoplayer2.util.Assertions; /** - * A representation of media currently available for playback. - *

- * Timeline instances are immutable. For cases where the available media is changing dynamically - * (e.g. live streams) a timeline provides a snapshot of the media currently available. + * 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 related {@link Period}s and {@link Window}s. A period defines a single - * logical piece of media, for example a media file. 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. + * 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. * *

Single media file or on-demand stream

*

@@ -78,28 +81,36 @@ import com.google.android.exoplayer2.util.Assertions; * with multiple periods"> *

* This case arises when a live stream is explicitly divided into separate periods, for example at - * content and advert 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. + * 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 pre-roll followed by live stream

+ *

On-demand stream followed by live stream

*

- * Example timeline for an on-demand pre-roll + * <img src= *

* 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 pre-roll ends, playback of the live stream will start from its default position near the - * live edge. + * 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. */ 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. See {@link Timeline} for more details. 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. + * 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. *

* Information defined by a timeline window *

@@ -235,9 +246,11 @@ public abstract class Timeline { /** * Holds information about a period in a {@link Timeline}. A period defines a single logical piece - * of media, for example a media file. See {@link Timeline} for more details. The figure below - * shows some of the information defined by a period, as well as how this information relates to a - * corresponding {@link Window} in the timeline. + * 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 {@link Window} in the timeline. *

* Information defined by a period *

diff --git a/library/core/src/main/javadoc/com/google/android/exoplayer2/doc-files/timeline-single-file-midrolls.svg b/library/core/src/main/javadoc/com/google/android/exoplayer2/doc-files/timeline-single-file-midrolls.svg new file mode 100644 index 0000000000..a364587320 --- /dev/null +++ b/library/core/src/main/javadoc/com/google/android/exoplayer2/doc-files/timeline-single-file-midrolls.svg @@ -0,0 +1,51 @@ + + + + Produced by OmniGraffle 7.4 + 2017-07-19 14:26:00 +0000 + + + + + + + + + + + + + + + Canvas 1 + + + Layer 1 + + + + period1 + + + + + window1 + + + + + + + time + + + + + + + + + + + +