Expose period information from MediaSources.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=128357449

demo/src/main/java/com/google/android/exoplayer2/demo/EventLogger.java

@@ -24,6 +24,7 @@ import com.google.android.exoplayer2.decoder.DecoderCounters;
 import com.google.android.exoplayer2.drm.StreamingDrmSessionManager;
 import com.google.android.exoplayer2.source.AdaptiveMediaSourceEventListener;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.source.TrackGroup;
 import com.google.android.exoplayer2.source.TrackGroupArray;
 import com.google.android.exoplayer2.trackselection.MappingTrackSelector;
@@ -88,6 +89,14 @@ public class EventLogger implements ExoPlayer.EventListener, SimpleExoPlayer.Deb
   }
 
   @Override
+  public void onTimelineChanged(Timeline timeline) {
+    boolean isFinal = timeline.isFinal();
+    int periodCount = timeline.getPeriodCount();
+    Log.d(TAG, "timelineChanged [" + isFinal + ", "
+        + (periodCount == Timeline.UNKNOWN_PERIOD_COUNT ? "?" : periodCount) + "]");
+  }
+
+  @Override
   public void onPlayerError(ExoPlaybackException e) {
     Log.e(TAG, "playerFailed [" + getSessionTimeString() + "]", e);
   }

demo/src/main/java/com/google/android/exoplayer2/demo/PlayerActivity.java

@@ -37,6 +37,7 @@ import com.google.android.exoplayer2.metadata.id3.TxxxFrame;
 import com.google.android.exoplayer2.source.ConcatenatingMediaSource;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.source.TrackGroupArray;
 import com.google.android.exoplayer2.source.chunk.FormatEvaluator;
 import com.google.android.exoplayer2.source.chunk.FormatEvaluator.AdaptiveEvaluator;
@@ -458,6 +459,11 @@ public class PlayerActivity extends Activity implements SurfaceHolder.Callback,
   }
 
   @Override
+  public void onTimelineChanged(Timeline timeline) {
+    // Do nothing.
+  }
+
+  @Override
   public void onPlayerError(ExoPlaybackException e) {
     String errorString = null;
     if (e.type == ExoPlaybackException.TYPE_RENDERER) {

extensions/flac/src/androidTest/java/com/google/android/exoplayer2/ext/flac/FlacPlaybackTest.java

@@ -21,6 +21,7 @@ import com.google.android.exoplayer2.ExoPlayerFactory;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.extractor.mkv.MatroskaExtractor;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.trackselection.DefaultTrackSelector;
 import com.google.android.exoplayer2.upstream.DefaultDataSourceFactory;
 
@@ -101,6 +102,11 @@ public class FlacPlaybackTest extends InstrumentationTestCase {
     }
 
     @Override
+    public void onTimelineChanged(Timeline timeline) {
+      // Do nothing.
+    }
+
+    @Override
     public void onPlayerError(ExoPlaybackException error) {
       playbackException = error;
     }

extensions/opus/src/androidTest/java/com/google/android/exoplayer2/ext/opus/OpusPlaybackTest.java

@@ -21,6 +21,7 @@ import com.google.android.exoplayer2.ExoPlayerFactory;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.extractor.mkv.MatroskaExtractor;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.trackselection.DefaultTrackSelector;
 import com.google.android.exoplayer2.upstream.DefaultDataSourceFactory;
 
@@ -101,6 +102,11 @@ public class OpusPlaybackTest extends InstrumentationTestCase {
     }
 
     @Override
+    public void onTimelineChanged(Timeline timeline) {
+      // Do nothing.
+    }
+
+    @Override
     public void onPlayerError(ExoPlaybackException error) {
       playbackException = error;
     }

extensions/vp9/src/androidTest/java/com/google/android/exoplayer2/ext/vp9/VpxPlaybackTest.java

@@ -21,6 +21,7 @@ import com.google.android.exoplayer2.ExoPlayerFactory;
 import com.google.android.exoplayer2.Renderer;
 import com.google.android.exoplayer2.extractor.mkv.MatroskaExtractor;
 import com.google.android.exoplayer2.source.ExtractorMediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.trackselection.DefaultTrackSelector;
 import com.google.android.exoplayer2.upstream.DefaultDataSourceFactory;
 
@@ -120,6 +121,11 @@ public class VpxPlaybackTest extends InstrumentationTestCase {
     }
 
     @Override
+    public void onTimelineChanged(Timeline timeline) {
+      // Do nothing.
+    }
+
+    @Override
     public void onPlayerError(ExoPlaybackException error) {
       playbackException = error;
     }

library/src/main/java/com/google/android/exoplayer2/ExoPlayer.java

@@ -17,6 +17,7 @@ package com.google.android.exoplayer2;
 
 import com.google.android.exoplayer2.source.MediaPeriod;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 
 /**
  * An extensible media player exposing traditional high-level media player functionality, such as
@@ -139,6 +140,13 @@ public interface ExoPlayer {
     void onPositionDiscontinuity(int periodIndex, long positionMs);
 
     /**
+     * Invoked when the timeline changes.
+     *
+     * @param timeline The new timeline.
+     */
+    void onTimelineChanged(Timeline timeline);
+
+    /**
      * Invoked when an error occurs. The playback state will transition to
      * {@link ExoPlayer#STATE_IDLE} immediately after this method is invoked. The player instance
      * can still be used, and {@link ExoPlayer#release()} must still be called on the player should
@@ -329,10 +337,10 @@ public interface ExoPlayer {
   void blockingSendMessages(ExoPlayerMessage... messages);
 
   /**
-   * Gets the duration of the track in milliseconds.
+   * Gets the duration of the current period in milliseconds.
    *
-   * @return The duration of the track in milliseconds, or {@link ExoPlayer#UNKNOWN_TIME} if the
-   *     duration is not known.
+   * @return The duration of the current period in milliseconds, or {@link ExoPlayer#UNKNOWN_TIME}
+   *     if the duration is not known.
    */
   long getDuration();
 
@@ -351,6 +359,13 @@ public interface ExoPlayer {
   int getCurrentPeriodIndex();
 
   /**
+   * Gets the current {@link Timeline}, or {@code null} if there is no timeline.
+   *
+   * @return The current {@link Timeline}, or {@code null} if there is no timeline.
+   */
+  Timeline getCurrentTimeline();
+
+  /**
    * Gets an estimate of the absolute position in milliseconds up to which data is buffered.
    *
    * @return An estimate of the absolute position in milliseconds up to which data is buffered,

library/src/main/java/com/google/android/exoplayer2/ExoPlayerImpl.java

@@ -17,6 +17,7 @@ package com.google.android.exoplayer2;
 
 import com.google.android.exoplayer2.ExoPlayerImplInternal.PlaybackInfo;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.trackselection.TrackSelector;
 import com.google.android.exoplayer2.util.Assertions;
 
@@ -44,6 +45,7 @@ import java.util.concurrent.CopyOnWriteArraySet;
   private int pendingPlayWhenReadyAcks;
   private int pendingSeekAcks;
   private boolean isLoading;
+  private Timeline timeline;
 
   // Playback information when there is no pending seek/set source operation.
   private PlaybackInfo playbackInfo;
@@ -75,9 +77,9 @@ import java.util.concurrent.CopyOnWriteArraySet;
         ExoPlayerImpl.this.handleEvent(msg);
       }
     };
-    internalPlayer = new ExoPlayerImplInternal(renderers, trackSelector, loadControl, playWhenReady,
-        eventHandler);
     playbackInfo = new ExoPlayerImplInternal.PlaybackInfo(0);
+    internalPlayer = new ExoPlayerImplInternal(renderers, trackSelector, loadControl, playWhenReady,
+        eventHandler, playbackInfo);
   }
 
   @Override
@@ -97,6 +99,7 @@ import java.util.concurrent.CopyOnWriteArraySet;
 
   @Override
   public void setMediaSource(MediaSource mediaSource) {
+    timeline = null;
     internalPlayer.setMediaSource(mediaSource);
   }
 
@@ -189,6 +192,11 @@ import java.util.concurrent.CopyOnWriteArraySet;
   }
 
   @Override
+  public Timeline getCurrentTimeline() {
+    return timeline;
+  }
+
+  @Override
   public long getBufferedPosition() {
     if (pendingSeekAcks == 0) {
       long bufferedPositionUs = playbackInfo.bufferedPositionUs;
@@ -245,6 +253,13 @@ import java.util.concurrent.CopyOnWriteArraySet;
         }
         break;
       }
+      case ExoPlayerImplInternal.MSG_TIMELINE_CHANGED: {
+        timeline = (Timeline) msg.obj;
+        for (EventListener listener : listeners) {
+          listener.onTimelineChanged(timeline);
+        }
+        break;
+      }
       case ExoPlayerImplInternal.MSG_ERROR: {
         ExoPlaybackException exception = (ExoPlaybackException) msg.obj;
         for (EventListener listener : listeners) {

library/src/main/java/com/google/android/exoplayer2/SimpleExoPlayer.java

@@ -26,11 +26,13 @@ import com.google.android.exoplayer2.metadata.MetadataRenderer;
 import com.google.android.exoplayer2.metadata.id3.Id3Decoder;
 import com.google.android.exoplayer2.metadata.id3.Id3Frame;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.text.Cue;
 import com.google.android.exoplayer2.text.TextRenderer;
 import com.google.android.exoplayer2.trackselection.TrackSelector;
 import com.google.android.exoplayer2.video.MediaCodecVideoRenderer;
 import com.google.android.exoplayer2.video.VideoRendererEventListener;
+
 import android.annotation.TargetApi;
 import android.content.Context;
 import android.media.AudioManager;
@@ -390,6 +392,11 @@ public final class SimpleExoPlayer implements ExoPlayer {
   }
 
   @Override
+  public Timeline getCurrentTimeline() {
+    return player.getCurrentTimeline();
+  }
+
+  @Override
   public long getBufferedPosition() {
     return player.getBufferedPosition();
   }

library/src/main/java/com/google/android/exoplayer2/source/ConcatenatingMediaSource.java

@@ -15,7 +15,10 @@
  */
 package com.google.android.exoplayer2.source;
 
+import com.google.android.exoplayer2.util.Util;
+
 import java.io.IOException;
+import java.util.Arrays;
 
 /**
  * Concatenates multiple {@link MediaSource}s.
@@ -23,45 +26,50 @@ import java.io.IOException;
 public final class ConcatenatingMediaSource implements MediaSource {
 
   private final MediaSource[] mediaSources;
+  private final Timeline[] timelines;
+
+  private ConcatenatedTimeline timeline;
 
   /**
    * @param mediaSources The {@link MediaSource}s to concatenate.
    */
   public ConcatenatingMediaSource(MediaSource... mediaSources) {
     this.mediaSources = mediaSources;
+    timelines = new Timeline[mediaSources.length];
   }
 
   @Override
-  public void prepareSource() {
-    for (MediaSource mediaSource : mediaSources) {
-      mediaSource.prepareSource();
+  public void prepareSource(final InvalidationListener listener) {
+    for (int i = 0; i < mediaSources.length; i++) {
+      final int index = i;
+      mediaSources[i].prepareSource(new InvalidationListener() {
+        @Override
+        public void onTimelineChanged(Timeline timeline) {
+          timelines[index] = timeline;
+          ConcatenatingMediaSource.this.timeline = new ConcatenatedTimeline(timelines.clone());
+          listener.onTimelineChanged(ConcatenatingMediaSource.this.timeline);
+        }
+      });
     }
   }
 
   @Override
-  public int getPeriodCount() {
-    int sourceCount = 0;
-    for (MediaSource mediaSource : mediaSources) {
-      int count = mediaSource.getPeriodCount();
-      if (count == MediaSource.UNKNOWN_PERIOD_COUNT) {
-        return UNKNOWN_PERIOD_COUNT;
-      }
-      sourceCount += count;
-    }
-    return sourceCount;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline)
+      throws IOException {
+    ConcatenatedTimeline oldConcatenatedTimeline = (ConcatenatedTimeline) oldTimeline;
+    int sourceIndex = oldConcatenatedTimeline.getSourceIndexForPeriod(oldPlayingPeriodIndex);
+    int sourceFirstPeriodIndex = oldConcatenatedTimeline.getFirstPeriodIndexInSource(sourceIndex);
+    return sourceFirstPeriodIndex == Timeline.NO_PERIOD_INDEX ? Timeline.NO_PERIOD_INDEX
+        : sourceFirstPeriodIndex + mediaSources[sourceIndex].getNewPlayingPeriodIndex(
+            oldPlayingPeriodIndex - sourceFirstPeriodIndex,
+            oldConcatenatedTimeline.timelines[sourceIndex]);
   }
 
   @Override
   public MediaPeriod createPeriod(int index) throws IOException {
-    int sourceCount = 0;
-    for (MediaSource mediaSource : mediaSources) {
-      int count = mediaSource.getPeriodCount();
-      if (count == MediaSource.UNKNOWN_PERIOD_COUNT || index < sourceCount + count) {
-        return mediaSource.createPeriod(index - sourceCount);
-      }
-      sourceCount += count;
-    }
-    throw new IndexOutOfBoundsException();
+    int sourceIndex = timeline.getSourceIndexForPeriod(index);
+    int periodIndexInSource = index - timeline.getFirstPeriodIndexInSource(sourceIndex);
+    return mediaSources[sourceIndex].createPeriod(periodIndexInSource);
   }
 
   @Override
@@ -71,4 +79,99 @@ public final class ConcatenatingMediaSource implements MediaSource {
     }
   }
 
+  /**
+   * A {@link Timeline} that is the concatenation of one or more {@link Timeline}s.
+   */
+  private static final class ConcatenatedTimeline implements Timeline {
+
+    private final Timeline[] timelines;
+    private final Object[] manifests;
+    private final int count;
+    private final boolean isFinal;
+    private int[] sourceOffsets;
+
+    public ConcatenatedTimeline(Timeline[] timelines) {
+      this.timelines = timelines;
+
+      int[] sourceOffsets = new int[timelines.length];
+      int sourceIndexOffset = 0;
+      for (int i = 0; i < timelines.length; i++) {
+        Timeline manifest = timelines[i];
+        int periodCount;
+        if (manifest == null
+            || (periodCount = manifest.getPeriodCount()) == Timeline.UNKNOWN_PERIOD_COUNT) {
+          sourceOffsets = Arrays.copyOf(sourceOffsets, i);
+          break;
+        }
+        sourceIndexOffset += periodCount;
+        sourceOffsets[i] = sourceIndexOffset;
+      }
+      this.sourceOffsets = sourceOffsets;
+      count = sourceOffsets.length == timelines.length ? sourceOffsets[sourceOffsets.length - 1]
+          : UNKNOWN_PERIOD_COUNT;
+      boolean isFinal = true;
+      manifests = new Object[timelines.length];
+      for (int i = 0; i < timelines.length; i++) {
+        Timeline timeline = timelines[i];
+        if (timeline != null) {
+          manifests[i] = timeline.getManifest();
+          if (!timeline.isFinal()) {
+            isFinal = false;
+          }
+        }
+      }
+      this.isFinal = isFinal;
+    }
+
+    @Override
+    public int getPeriodCount() {
+      return count;
+    }
+
+    @Override
+    public boolean isFinal() {
+      return isFinal;
+    }
+
+    @Override
+    public long getPeriodDuration(int index) {
+      int sourceIndex = getSourceIndexForPeriod(index);
+      return timelines[sourceIndex].getPeriodDuration(sourceIndex);
+    }
+
+    @Override
+    public Object getPeriodId(int index) {
+      int sourceIndex = getSourceIndexForPeriod(index);
+      int firstPeriodIndexInSource = getFirstPeriodIndexInSource(index);
+      return timelines[sourceIndex].getPeriodId(index - firstPeriodIndexInSource);
+    }
+
+    @Override
+    public int getIndexOfPeriod(Object id) {
+      for (int sourceIndex = 0; sourceIndex < timelines.length; sourceIndex++) {
+        int periodIndexInSource = timelines[sourceIndex].getIndexOfPeriod(id);
+        if (periodIndexInSource != NO_PERIOD_INDEX) {
+          int firstPeriodIndexInSource = getFirstPeriodIndexInSource(sourceIndex);
+          return firstPeriodIndexInSource + periodIndexInSource;
+        }
+      }
+      return NO_PERIOD_INDEX;
+    }
+
+    @Override
+    public Object getManifest() {
+      return manifests;
+    }
+
+    private int getSourceIndexForPeriod(int periodIndex) {
+      return Util.binarySearchFloor(sourceOffsets, periodIndex, true, false) + 1;
+    }
+
+    private int getFirstPeriodIndexInSource(int sourceIndex) {
+      return sourceIndex == 0 ? 0 : sourceIndex > sourceOffsets.length
+          ? Timeline.NO_PERIOD_INDEX : sourceOffsets[sourceIndex - 1];
+    }
+
+  }
+
 }

library/src/main/java/com/google/android/exoplayer2/source/ExtractorMediaSource.java

@@ -180,13 +180,13 @@ public final class ExtractorMediaSource implements MediaPeriod, MediaSource,
   // MediaSource implementation.
 
   @Override
-  public void prepareSource() {
-    // do nothing
+  public void prepareSource(InvalidationListener listener) {
+    listener.onTimelineChanged(new SinglePeriodTimeline(this));
   }
 
   @Override
-  public int getPeriodCount() {
-    return 1;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) {
+    return oldPlayingPeriodIndex;
   }
 
   @Override

library/src/main/java/com/google/android/exoplayer2/source/MediaSource.java

@@ -23,28 +23,44 @@ import java.io.IOException;
 public interface MediaSource {
 
   /**
-   * Returned by {@link #getPeriodCount()} if the number of periods is not known.
+   * Listener for invalidation events.
    */
-  int UNKNOWN_PERIOD_COUNT = -1;
+  interface InvalidationListener {
+
+    /**
+     * Invoked when the timeline is invalidated.
+     * <p>
+     * May only be called on the player's thread.
+     *
+     * @param timeline The new timeline.
+     */
+    void onTimelineChanged(Timeline timeline);
+
+  }
 
   /**
    * Starts preparation of the source.
+   *
+   * @param listener The listener for source invalidation events.
    */
-  void prepareSource();
+  void prepareSource(InvalidationListener listener);
 
   /**
-   * Returns the number of periods in the source, or {@link #UNKNOWN_PERIOD_COUNT} if the number
-   * of periods is not yet known.
+   * Returns the period index to play in this source's new timeline.
+   *
+   * @param oldPlayingPeriodIndex The period index that was being played in the old timeline.
+   * @param oldTimeline The old timeline.
+   * @return The period index to play in this source's new timeline.
+   * @throws IOException Thrown if the required period can't be loaded.
    */
-  int getPeriodCount();
+  int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) throws IOException;
 
   /**
    * Returns a {@link MediaPeriod} corresponding to the period at the specified index, or
    * {@code null} if the period at the specified index is not yet available.
    *
-   * @param index The index of the period. Must be less than {@link #getPeriodCount()} unless the
-   *     period count is {@link #UNKNOWN_PERIOD_COUNT}.
-   * @return A {@link MediaPeriod}, or {@code null} if the source at the specified index is not yet
+   * @param index The index of the period.
+   * @return A {@link MediaPeriod}, or {@code null} if the source at the specified index is not
    *     available.
    * @throws IOException If there is an error that's preventing the source from becoming prepared or
    *     creating periods.

library/src/main/java/com/google/android/exoplayer2/source/MergingMediaSource.java

@@ -22,38 +22,47 @@ import java.io.IOException;
 /**
  * Merges multiple {@link MediaPeriod} instances.
  * <p>
- * The {@link MediaSource}s being merged must have known and equal period counts, and may not return
- * {@code null} from {@link #createPeriod(int)}.
+ * The {@link MediaSource}s being merged must have final timelines and equal period counts.
  */
 public final class MergingMediaSource implements MediaSource {
 
   private final MediaSource[] mediaSources;
-  private final int periodCount;
+
+  private int periodCount;
 
   /**
    * @param mediaSources The {@link MediaSource}s to merge.
    */
   public MergingMediaSource(MediaSource... mediaSources) {
     this.mediaSources = mediaSources;
-    periodCount = mediaSources[0].getPeriodCount();
-    Assertions.checkState(periodCount != UNKNOWN_PERIOD_COUNT,
-        "Child sources must have known period counts");
-    for (MediaSource mediaSource : mediaSources) {
-      Assertions.checkState(mediaSource.getPeriodCount() == periodCount,
-          "Child sources must have equal period counts");
-    }
+    periodCount = -1;
   }
 
   @Override
-  public void prepareSource() {
-    for (MediaSource mediaSource : mediaSources) {
-      mediaSource.prepareSource();
+  public void prepareSource(final InvalidationListener listener) {
+    mediaSources[0].prepareSource(new InvalidationListener() {
+      @Override
+      public void onTimelineChanged(Timeline timeline) {
+        checkConsistentTimeline(timeline);
+
+        // All source timelines must match.
+        listener.onTimelineChanged(timeline);
+      }
+    });
+    for (int i = 1; i < mediaSources.length; i++) {
+      mediaSources[i].prepareSource(new InvalidationListener() {
+        @Override
+        public void onTimelineChanged(Timeline timeline) {
+          checkConsistentTimeline(timeline);
+        }
+      });
     }
   }
 
   @Override
-  public int getPeriodCount() {
-    return periodCount;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline)
+      throws IOException {
+    return mediaSources[0].getNewPlayingPeriodIndex(oldPlayingPeriodIndex, oldTimeline);
   }
 
   @Override
@@ -73,4 +82,14 @@ public final class MergingMediaSource implements MediaSource {
     }
   }
 
+  private void checkConsistentTimeline(Timeline timeline) {
+    Assertions.checkArgument(timeline.isFinal());
+    int periodCount = timeline.getPeriodCount();
+    if (this.periodCount == -1) {
+      this.periodCount = periodCount;
+    } else {
+      Assertions.checkState(this.periodCount == periodCount);
+    }
+  }
+
 }

library/src/main/java/com/google/android/exoplayer2/source/SinglePeriodTimeline.java

+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.android.exoplayer2.source;
+
+import com.google.android.exoplayer2.ExoPlayer;
+import com.google.android.exoplayer2.util.Assertions;
+
+/**
+ * A {@link Timeline} consisting of a single period.
+ */
+public final class SinglePeriodTimeline implements Timeline {
+
+  private final Object id;
+  private final Object manifest;
+  private final long duration;
+
+  /**
+   * Creates a new timeline with one period of unknown duration.
+   *
+   * @param id The identifier for the period.
+   */
+  public SinglePeriodTimeline(Object id) {
+    this(id, null);
+  }
+
+  /**
+   * Creates a new timeline with one period of unknown duration providing an optional manifest.
+   *
+   * @param id The identifier for the period.
+   * @param manifest The source-specific manifest that defined the period, or {@code null}.
+   */
+  public SinglePeriodTimeline(Object id, Object manifest) {
+    this(id, manifest, ExoPlayer.UNKNOWN_TIME);
+  }
+
+  /**
+   * Creates a new timeline with one period of the specified duration providing an optional
+   * manifest.
+   *
+   * @param id The identifier for the period.
+   * @param manifest The source-specific manifest that defined the period, or {@code null}.
+   * @param duration The duration of the period in milliseconds.
+   */
+  public SinglePeriodTimeline(Object id, Object manifest, long duration) {
+    this.id = Assertions.checkNotNull(id);
+    this.manifest = manifest;
+    this.duration = duration;
+  }
+
+  @Override
+  public int getPeriodCount() {
+    return 1;
+  }
+
+  @Override
+  public boolean isFinal() {
+    return true;
+  }
+
+  @Override
+  public long getPeriodDuration(int index) {
+    if (index != 0) {
+      throw new IndexOutOfBoundsException("Index " + index + " out of bounds");
+    }
+    return duration;
+  }
+
+  @Override
+  public Object getPeriodId(int index) {
+    return index == 0 ? id : null;
+  }
+
+  @Override
+  public int getIndexOfPeriod(Object id) {
+    return id.equals(this.id) ? 0 : Timeline.NO_PERIOD_INDEX;
+  }
+
+  @Override
+  public Object getManifest() {
+    return manifest;
+  }
+
+}

library/src/main/java/com/google/android/exoplayer2/source/SingleSampleMediaSource.java

@@ -115,13 +115,13 @@ public final class SingleSampleMediaSource implements MediaPeriod, MediaSource,
   // MediaSource implementation.
 
   @Override
-  public void prepareSource() {
-    // do nothing
+  public void prepareSource(InvalidationListener listener) {
+    listener.onTimelineChanged(new SinglePeriodTimeline(this));
   }
 
   @Override
-  public int getPeriodCount() {
-    return 1;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) {
+    return oldPlayingPeriodIndex;
   }
 
   @Override

library/src/main/java/com/google/android/exoplayer2/source/Timeline.java

+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.android.exoplayer2.source;
+
+import com.google.android.exoplayer2.ExoPlayer;
+
+/**
+ * The player's timeline consisting of one or more periods. Instances are immutable.
+ */
+public interface Timeline {
+
+  /**
+   * Returned by {@link #getPeriodCount()} when the number of periods is not known.
+   */
+  int UNKNOWN_PERIOD_COUNT = -1;
+
+  /**
+   * Returned by {@link #getIndexOfPeriod(Object)} if no period index corresponds to the specified
+   * identifier.
+   */
+  int NO_PERIOD_INDEX = -1;
+
+  /**
+   * Returns the number of periods in the timeline, or {@link #UNKNOWN_PERIOD_COUNT} if not known.
+   * If {@link #isFinal()} returns {@code true}, the number of periods must be known.
+   */
+  int getPeriodCount();
+
+  /**
+   * Returns whether the timeline is final, which means it will not be invalidated again.
+   */
+  boolean isFinal();
+
+  /**
+   * Returns the duration of the period at {@code index} in the timeline, in milliseconds, or
+   * {@link ExoPlayer#UNKNOWN_TIME} if not known.
+   *
+   * @param index The index of the period.
+   * @return The duration of the period in milliseconds, or {@link ExoPlayer#UNKNOWN_TIME}.
+   */
+  long getPeriodDuration(int index);
+
+  /**
+   * Returns a unique identifier for the period at {@code index}, or {@code null} if the period at
+   * {@code index} is not known. The identifier is stable across {@link Timeline} instances.
+   * <p>
+   * When a source is invalidated the player uses period identifiers to determine what periods are
+   * unchanged. Implementations that associate an object with each period can return the object for
+   * the provided index to guarantee uniqueness. Other implementations must be careful to return
+   * identifiers that can't clash with (for example) identifiers used by other timelines that may be
+   * concatenated with this one.
+   *
+   * @param index A period index.
+   * @return An identifier for the period, or {@code null} if the period is not known.
+   */
+  Object getPeriodId(int index);
+
+  /**
+   * Returns the index of the period identified by {@code id}, or {@link #NO_PERIOD_INDEX} if the
+   * period is not in the timeline.
+   *
+   * @param id An identifier for a period.
+   * @return The index of the period, or {@link #NO_PERIOD_INDEX} if the period was not found.
+   */
+  int getIndexOfPeriod(Object id);
+
+  /**
+   * Returns the immutable manifest corresponding to this timeline.
+   */
+  Object getManifest();
+
+}

library/src/main/java/com/google/android/exoplayer2/source/dash/DashMediaSource.java

@@ -21,6 +21,7 @@ import com.google.android.exoplayer2.source.AdaptiveMediaSourceEventListener;
 import com.google.android.exoplayer2.source.AdaptiveMediaSourceEventListener.EventDispatcher;
 import com.google.android.exoplayer2.source.MediaPeriod;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.source.dash.manifest.DashManifest;
 import com.google.android.exoplayer2.source.dash.manifest.DashManifestParser;
 import com.google.android.exoplayer2.source.dash.manifest.UtcTimingElement;
@@ -62,6 +63,7 @@ public final class DashMediaSource implements MediaSource {
   private final DashManifestParser manifestParser;
   private final ManifestCallback manifestCallback;
 
+  private MediaSource.InvalidationListener invalidationListener;
   private DataSource dataSource;
   private Loader loader;
 
@@ -95,7 +97,8 @@ public final class DashMediaSource implements MediaSource {
   // MediaSource implementation.
 
   @Override
-  public void prepareSource() {
+  public void prepareSource(InvalidationListener listener) {
+    invalidationListener = listener;
     dataSource = manifestDataSourceFactory.createDataSource();
     loader = new Loader("Loader:DashMediaSource");
     manifestRefreshHandler = new Handler();
@@ -103,11 +106,22 @@ public final class DashMediaSource implements MediaSource {
   }
 
   @Override
-  public int getPeriodCount() {
-    if (manifest == null) {
-      return UNKNOWN_PERIOD_COUNT;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) {
+    int periodIndex = oldPlayingPeriodIndex;
+    int oldPeriodCount = oldTimeline.getPeriodCount();
+    while (oldPeriodCount == Timeline.UNKNOWN_PERIOD_COUNT || periodIndex < oldPeriodCount) {
+      Object id = oldTimeline.getPeriodId(periodIndex);
+      if (id == null) {
+        break;
+      }
+      for (int i = 0; i < periods.length; i++) {
+        if (periods[i] == id) {
+          return i;
+        }
+      }
+      periodIndex++;
     }
-    return manifest.getPeriodCount();
+    return Timeline.NO_PERIOD_INDEX;
   }
 
   @Override
@@ -161,6 +175,8 @@ public final class DashMediaSource implements MediaSource {
       }
       scheduleManifestRefresh();
     }
+
+    invalidationListener.onTimelineChanged(new DashTimeline(manifest, periods));
   }
 
   /* package */ int onManifestLoadError(ParsingLoadable<DashManifest> loadable,
@@ -278,6 +294,53 @@ public final class DashMediaSource implements MediaSource {
     eventDispatcher.loadStarted(loadable.dataSpec, loadable.type, elapsedRealtimeMs);
   }
 
+  private static final class DashTimeline implements Timeline {
+
+    private final DashManifest manifest;
+    private final DashMediaPeriod[] periods;
+
+    public DashTimeline(DashManifest manifest, DashMediaPeriod[] periods) {
+      this.manifest = manifest;
+      this.periods = periods;
+    }
+
+    @Override
+    public int getPeriodCount() {
+      return manifest.getPeriodCount();
+    }
+
+    @Override
+    public boolean isFinal() {
+      return !manifest.dynamic;
+    }
+
+    @Override
+    public long getPeriodDuration(int index) {
+      return manifest.getPeriodDuration(index);
+    }
+
+    @Override
+    public Object getPeriodId(int index) {
+      return index >= periods.length ? null : periods[index];
+    }
+
+    @Override
+    public int getIndexOfPeriod(Object id) {
+      for (int i = 0; i < periods.length; i++) {
+        if (id == periods[i]) {
+          return i;
+        }
+      }
+      return Timeline.NO_PERIOD_INDEX;
+    }
+
+    @Override
+    public Object getManifest() {
+      return manifest;
+    }
+
+  }
+
   private final class ManifestCallback implements
       Loader.Callback<ParsingLoadable<DashManifest>> {
 

library/src/main/java/com/google/android/exoplayer2/source/hls/HlsMediaSource.java

@@ -24,6 +24,8 @@ import com.google.android.exoplayer2.source.CompositeSequenceableLoader;
 import com.google.android.exoplayer2.source.MediaPeriod;
 import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.source.SampleStream;
+import com.google.android.exoplayer2.source.SinglePeriodTimeline;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.source.TrackGroup;
 import com.google.android.exoplayer2.source.TrackGroupArray;
 import com.google.android.exoplayer2.source.chunk.FormatEvaluator;
@@ -110,13 +112,14 @@ public final class HlsMediaSource implements MediaPeriod, MediaSource,
   // MediaSource implementation.
 
   @Override
-  public void prepareSource() {
-    // do nothing
+  public void prepareSource(InvalidationListener listener) {
+    // TODO: Defer until the playlist has been loaded.
+    listener.onTimelineChanged(new SinglePeriodTimeline(this));
   }
 
   @Override
-  public int getPeriodCount() {
-    return 1;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) {
+    return oldPlayingPeriodIndex;
   }
 
   @Override

library/src/main/java/com/google/android/exoplayer2/source/smoothstreaming/SsMediaSource.java

@@ -26,6 +26,8 @@ import com.google.android.exoplayer2.source.MediaPeriod;
 import com.google.android.exoplayer2.source.MediaSource;
 import com.google.android.exoplayer2.source.SampleStream;
 import com.google.android.exoplayer2.source.SequenceableLoader;
+import com.google.android.exoplayer2.source.SinglePeriodTimeline;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.source.TrackGroup;
 import com.google.android.exoplayer2.source.TrackGroupArray;
 import com.google.android.exoplayer2.source.chunk.ChunkSampleStream;
@@ -72,6 +74,7 @@ public final class SsMediaSource implements MediaPeriod, MediaSource,
   private final EventDispatcher eventDispatcher;
   private final SsManifestParser manifestParser;
 
+  private MediaSource.InvalidationListener invalidationListener;
   private DataSource manifestDataSource;
   private Loader manifestLoader;
   private ChunkSampleStream<SsChunkSource>[] sampleStreams;
@@ -111,13 +114,13 @@ public final class SsMediaSource implements MediaPeriod, MediaSource,
   // MediaSource implementation.
 
   @Override
-  public void prepareSource() {
-    // do nothing
+  public void prepareSource(InvalidationListener listener) {
+    this.invalidationListener = listener;
   }
 
   @Override
-  public int getPeriodCount() {
-    return 1;
+  public int getNewPlayingPeriodIndex(int oldPlayingPeriodIndex, Timeline oldTimeline) {
+    return oldPlayingPeriodIndex;
   }
 
   @Override
@@ -273,6 +276,9 @@ public final class SsMediaSource implements MediaPeriod, MediaSource,
     manifestLoadStartTimestamp = elapsedRealtimeMs - loadDurationMs;
     if (!prepared) {
       durationUs = manifest.durationUs;
+      Timeline timeline = durationUs == C.UNSET_TIME_US ? new SinglePeriodTimeline(this, manifest)
+          : new SinglePeriodTimeline(this, manifest, durationUs / 1000);
+      invalidationListener.onTimelineChanged(timeline);
       buildTrackGroups(manifest);
       ProtectionElement protectionElement = manifest.protectionElement;
       if (protectionElement != null) {

library/src/main/java/com/google/android/exoplayer2/ui/DebugTextViewHelper.java

@@ -20,6 +20,7 @@ import com.google.android.exoplayer2.ExoPlayer;
 import com.google.android.exoplayer2.Format;
 import com.google.android.exoplayer2.SimpleExoPlayer;
 import com.google.android.exoplayer2.decoder.DecoderCounters;
+import com.google.android.exoplayer2.source.Timeline;
 
 import android.widget.TextView;
 
@@ -164,6 +165,11 @@ public final class DebugTextViewHelper implements Runnable, ExoPlayer.EventListe
   }
 
   @Override
+  public void onTimelineChanged(Timeline timeline) {
+    // Do nothing.
+  }
+
+  @Override
   public void onPlayerError(ExoPlaybackException error) {
     // Do nothing.
   }

library/src/main/java/com/google/android/exoplayer2/util/Util.java

@@ -269,6 +269,26 @@ public final class Util {
    * @param stayInBounds If true, then 0 will be returned in the case that the key is smaller than
    *     the smallest value in the array. If false then -1 will be returned.
    */
+  public static int binarySearchFloor(int[] a, int key, boolean inclusive, boolean stayInBounds) {
+    int index = Arrays.binarySearch(a, key);
+    index = index < 0 ? -(index + 2) : (inclusive ? index : (index - 1));
+    return stayInBounds ? Math.max(0, index) : index;
+  }
+
+  /**
+   * Returns the index of the largest value in an array that is less than (or optionally equal to)
+   * a specified key.
+   * <p>
+   * The search is performed using a binary search algorithm, and so the array must be sorted.
+   *
+   * @param a The array to search.
+   * @param key The key being searched for.
+   * @param inclusive If the key is present in the array, whether to return the corresponding index.
+   *     If false then the returned index corresponds to the largest value in the array that is
+   *     strictly less than the key.
+   * @param stayInBounds If true, then 0 will be returned in the case that the key is smaller than
+   *     the smallest value in the array. If false then -1 will be returned.
+   */
   public static int binarySearchFloor(long[] a, long key, boolean inclusive, boolean stayInBounds) {
     int index = Arrays.binarySearch(a, key);
     index = index < 0 ? -(index + 2) : (inclusive ? index : (index - 1));

playbacktests/src/main/java/com/google/android/exoplayer2/playbacktests/util/ExoHostedTest.java

@@ -26,6 +26,7 @@ import com.google.android.exoplayer2.decoder.DecoderCounters;
 import com.google.android.exoplayer2.drm.DrmSessionManager;
 import com.google.android.exoplayer2.playbacktests.util.HostActivity.HostedTest;
 import com.google.android.exoplayer2.source.MediaSource;
+import com.google.android.exoplayer2.source.Timeline;
 import com.google.android.exoplayer2.trackselection.DefaultTrackSelector;
 import com.google.android.exoplayer2.trackselection.MappingTrackSelector;
 import com.google.android.exoplayer2.util.Util;
@@ -34,6 +35,7 @@ import android.os.Handler;
 import android.os.SystemClock;
 import android.util.Log;
 import android.view.Surface;
+
 import junit.framework.Assert;
 
 
@@ -212,6 +214,11 @@ public abstract class ExoHostedTest implements HostedTest, ExoPlayer.EventListen
     // Do nothing.
   }
 
+  @Override
+  public final void onTimelineChanged(Timeline timeline) {
+    // Do nothing.
+  }
+
   // SimpleExoPlayer.DebugListener
 
   @Override