diff --git a/library/src/main/java/com/google/android/exoplayer2/Timeline.java b/library/src/main/java/com/google/android/exoplayer2/Timeline.java
index 65c208fe24..1fba044e4f 100644
--- a/library/src/main/java/com/google/android/exoplayer2/Timeline.java
+++ b/library/src/main/java/com/google/android/exoplayer2/Timeline.java
@@ -16,7 +16,78 @@
package com.google.android.exoplayer2;
/**
- * A media timeline. Instances are immutable.
+ * 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 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
+ * start 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
+ *
+ *
+ *
+ * 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 start 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
+ *
+ *
+ *
+ * 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 start 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
+ *
+ *
+ *
+ * A timeline for a live stream consists of a period whose duration is unknown, since its
+ * 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 start position is typically near to the live edge
+ * (indicated by the black dot in the figure above).
+ *
+ *
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
+ *
+ *
+ *
+ * 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.
+ *
+ *
On-demand pre-roll followed by 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 pre-roll ends, playback of the live stream will start from its default start position near
+ * the live edge.
*/
public abstract class Timeline {
@@ -87,7 +158,14 @@ public abstract class Timeline {
public abstract int getIndexOfPeriod(Object uid);
/**
- * Holds information about a window of available media.
+ * 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.
+ *
+ *
+ *
*/
public static final class Window {
@@ -200,7 +278,13 @@ public abstract class Timeline {
}
/**
- * Holds information about a media period.
+ * Holds information about a period in a {@link Timeline}. A period defines a single logical piece
+ * of media, for example a 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.
+ *
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ * 
+ *