Package com.google.android.exoplayer2.source

## Interface MediaSource

- All Known Implementing Classes:
    `AdsMediaSource`, `BaseMediaSource`, `ClippingMediaSource`, `CompositeMediaSource`, `ConcatenatingMediaSource`, `ConcatenatingMediaSource2`, `DashMediaSource`, `FakeAdaptiveMediaSource`, `FakeMediaSource`, `HlsMediaSource`, `ImaServerSideAdInsertionMediaSource`, `LoopingMediaSource`, `MaskingMediaSource`, `MergingMediaSource`, `ProgressiveMediaSource`, `RtspMediaSource`, `ServerSideAdInsertionMediaSource`, `SilenceMediaSource`, `SingleSampleMediaSource`, `SsMediaSource`, `WrappingMediaSource`

      public interface MediaSource

  Defines and provides media to be played by an `ExoPlayer`. A MediaSource has two main responsibilities:
  - To provide the player with a `Timeline` defining the structure of its media, and to provide a new timeline whenever the structure of the media changes. The MediaSource provides these timelines by calling `MediaSource.MediaSourceCaller.onSourceInfoRefreshed(com.google.android.exoplayer2.source.MediaSource, com.google.android.exoplayer2.Timeline)` on the `MediaSource.MediaSourceCaller`s passed to `prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.
  - To provide `MediaPeriod` instances for the periods in its timeline. MediaPeriods are obtained by calling `createPeriod(MediaPeriodId, Allocator, long)`, and provide a way for the player to load and read the media.
  All methods are called on the player's internal playback thread, as described in the `ExoPlayer` Javadoc. They should not be called directly from application code. Instances can be re-used, but only for one `ExoPlayer` instance simultaneously.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `MediaSource.Factory` | Factory for creating `MediaSources` from `MediaItems`.
    `static class` | `MediaSource.MediaPeriodId` | Identifier for a `MediaPeriod`.
    `static interface` | `MediaSource.MediaSourceCaller` | A caller of media sources, which will be notified of source events.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addDrmEventListener​(Handler handler, DrmSessionEventListener eventListener)` | Adds a `DrmSessionEventListener` to the list of listeners which are notified of DRM events for this media source.
    `void` | `addEventListener​(Handler handler, MediaSourceEventListener eventListener)` | Adds a `MediaSourceEventListener` to the list of listeners which are notified of media source events.
    `MediaPeriod` | `createPeriod​(MediaSource.MediaPeriodId id, Allocator allocator, long startPositionUs)` | Returns a new `MediaPeriod` identified by `periodId`.
    `void` | `disable​(MediaSource.MediaSourceCaller caller)` | Disables the source for the creation of `MediaPeriods`.
    `void` | `enable​(MediaSource.MediaSourceCaller caller)` | Enables the source for the creation of `MediaPeriods`.
    `default Timeline` | `getInitialTimeline()` | Returns the initial placeholder timeline that is returned immediately when the real timeline is not yet known, or null to let the player create an initial timeline.
    `MediaItem` | `getMediaItem()` | Returns the `MediaItem` whose media is provided by the source.
    `default boolean` | `isSingleWindow()` | Returns true if the media source is guaranteed to never have zero or more than one window.
    `void` | `maybeThrowSourceInfoRefreshError()` | Throws any pending error encountered while loading or refreshing source information.
    `default void` | `prepareSource​(MediaSource.MediaSourceCaller caller, TransferListener mediaTransferListener)` | Deprecated. Implement `prepareSource(MediaSourceCaller, TransferListener, PlayerId)` instead.
    `void` | `prepareSource​(MediaSource.MediaSourceCaller caller, TransferListener mediaTransferListener, PlayerId playerId)` | Registers a `MediaSource.MediaSourceCaller`.
    `void` | `releasePeriod​(MediaPeriod mediaPeriod)` | Releases the period.
    `void` | `releaseSource​(MediaSource.MediaSourceCaller caller)` | Unregisters a caller, and disables and releases the source if no longer required.
    `void` | `removeDrmEventListener​(DrmSessionEventListener eventListener)` | Removes a `DrmSessionEventListener` from the list of listeners which are notified of DRM events for this media source.
    `void` | `removeEventListener​(MediaSourceEventListener eventListener)` | Removes a `MediaSourceEventListener` from the list of listeners which are notified of media source events.

- - ### Method Detail

    - #### addEventListener

          void addEventListener​(Handler handler,
                                MediaSourceEventListener eventListener)

      Adds a `MediaSourceEventListener` to the list of listeners which are notified of media source events.
      Parameters:
        `handler` - A handler on the which listener events will be posted.
        `eventListener` - The listener to be added.

    - #### removeEventListener

          void removeEventListener​(MediaSourceEventListener eventListener)

      Removes a `MediaSourceEventListener` from the list of listeners which are notified of media source events.
      Parameters:
        `eventListener` - The listener to be removed.

    - #### addDrmEventListener

          void addDrmEventListener​(Handler handler,
                                   DrmSessionEventListener eventListener)

      Adds a `DrmSessionEventListener` to the list of listeners which are notified of DRM events for this media source.
      Parameters:
        `handler` - A handler on the which listener events will be posted.
        `eventListener` - The listener to be added.

    - #### removeDrmEventListener

          void removeDrmEventListener​(DrmSessionEventListener eventListener)

      Removes a `DrmSessionEventListener` from the list of listeners which are notified of DRM events for this media source.
      Parameters:
        `eventListener` - The listener to be removed.

    - #### getInitialTimeline

          @Nullable
          default Timeline getInitialTimeline()

      Returns the initial placeholder timeline that is returned immediately when the real timeline is not yet known, or null to let the player create an initial timeline.

      The initial timeline must use the same uids for windows and periods that the real timeline will use. It also must provide windows which are marked as dynamic to indicate that the window is expected to change when the real timeline arrives.

      Any media source which has multiple windows should typically provide such an initial timeline to make sure the player reports the correct number of windows immediately.

    - #### isSingleWindow

          default boolean isSingleWindow()

      Returns true if the media source is guaranteed to never have zero or more than one window.

      The default implementation returns `true`.

      Returns:
        true if the source has exactly one window.

    - #### getMediaItem

          MediaItem getMediaItem()

      Returns the `MediaItem` whose media is provided by the source.

    - #### prepareSource

          @Deprecated
          default void prepareSource​(MediaSource.MediaSourceCaller caller,
                                     @Nullable
                                     TransferListener mediaTransferListener)

      Deprecated.
      Implement `prepareSource(MediaSourceCaller, TransferListener, PlayerId)` instead.

    - #### prepareSource

          void prepareSource​(MediaSource.MediaSourceCaller caller,
                             @Nullable
                             TransferListener mediaTransferListener,
                             PlayerId playerId)

      Registers a `MediaSource.MediaSourceCaller`. Starts source preparation if needed and enables the source for the creation of `MediaPerods`.

      Should not be called directly from application code.

      `MediaSource.MediaSourceCaller.onSourceInfoRefreshed(MediaSource, Timeline)` will be called once the source has a `Timeline`.

      For each call to this method, a call to `releaseSource(MediaSourceCaller)` is needed to remove the caller and to release the source if no longer required.

      Parameters:
        `caller` - The `MediaSource.MediaSourceCaller` to be registered.
        `mediaTransferListener` - The transfer listener which should be informed of any media data transfers. May be null if no listener is available. Note that this listener should be only informed of transfers related to the media loads and not of auxiliary loads for manifests and other data.
        `playerId` - The `PlayerId` of the player using this media source.

    - #### maybeThrowSourceInfoRefreshError

          void maybeThrowSourceInfoRefreshError()
                                         throws IOException

      Throws any pending error encountered while loading or refreshing source information.

      Should not be called directly from application code.

      Must only be called after `prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.

      Throws:
        `IOException`

    - #### enable

          void enable​(MediaSource.MediaSourceCaller caller)

      Enables the source for the creation of `MediaPeriods`.

      Should not be called directly from application code.

      Must only be called after `prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.

      Parameters:
        `caller` - The `MediaSource.MediaSourceCaller` enabling the source.

    - #### createPeriod

          MediaPeriod createPeriod​(MediaSource.MediaPeriodId id,
                                   Allocator allocator,
                                   long startPositionUs)

      Returns a new `MediaPeriod` identified by `periodId`.

      Should not be called directly from application code.

      Must only be called if the source is enabled.

      Parameters:
        `id` - The identifier of the period.
        `allocator` - An `Allocator` from which to obtain media buffer allocations.
        `startPositionUs` - The expected start position, in microseconds.
      Returns:
        A new `MediaPeriod`.

    - #### releasePeriod

          void releasePeriod​(MediaPeriod mediaPeriod)

      Releases the period.

      Should not be called directly from application code.

      Parameters:
        `mediaPeriod` - The period to release.

    - #### disable

          void disable​(MediaSource.MediaSourceCaller caller)

      Disables the source for the creation of `MediaPeriods`. The implementation should not hold onto limited resources used for the creation of media periods.

      Should not be called directly from application code.

      Must only be called after all `MediaPeriods` previously created by `createPeriod(MediaPeriodId, Allocator, long)` have been released by `releasePeriod(MediaPeriod)`.

      Parameters:
        `caller` - The `MediaSource.MediaSourceCaller` disabling the source.

    - #### releaseSource

          void releaseSource​(MediaSource.MediaSourceCaller caller)

      Unregisters a caller, and disables and releases the source if no longer required.

      Should not be called directly from application code.

      Must only be called if all created `MediaPeriods` have been released by `releasePeriod(MediaPeriod)`.

      Parameters:
        `caller` - The `MediaSource.MediaSourceCaller` to be unregistered.