ExoPlayer (library-core API)

All Known Implementing Classes:

SimpleExoPlayer
```
public interface ExoPlayer
```
An extensible media player exposing traditional high-level media player functionality, such as the ability to buffer media, play, pause and seek. Instances can be obtained from ExoPlayerFactory.
Player composition

ExoPlayer is designed to make few assumptions about (and hence impose few restrictions on) the type of the media being played, how and where it is stored, and how it is rendered. Rather than implementing the loading and rendering of media directly, ExoPlayer implementations delegate this work to components that are injected when a player is created or when it's prepared for playback. Components common to all ExoPlayer implementations are:
- A MediaSource that defines the media to be played, loads the media, and from which the loaded media can be read. A MediaSource is injected via prepare(com.google.android.exoplayer2.source.MediaSource) at the start of playback. The library modules provide default implementations for regular media files (ExtractorMediaSource), DASH (DashMediaSource), SmoothStreaming (SsMediaSource) and HLS (HlsMediaSource), implementations for merging (MergingMediaSource) and concatenating (ConcatenatingMediaSource) other MediaSources, and an implementation for loading single samples (SingleSampleMediaSource) most often used for side-loaded subtitle and closed caption files.
- Renderers that render individual components of the media. The library provides default implementations for common media types (MediaCodecVideoRenderer, MediaCodecAudioRenderer, TextRenderer and MetadataRenderer). A Renderer consumes media of its corresponding type from the MediaSource being played. Renderers are injected when the player is created.
- A TrackSelector that selects tracks provided by the MediaSource to be consumed by each of the available Renderers. The library provides a default implementation (DefaultTrackSelector) suitable for most use cases. A TrackSelector is injected when the player is created.
- A LoadControl that controls when the MediaSource buffers more media, and how much media is buffered. The library provides a default implementation (DefaultLoadControl) suitable for most use cases. A LoadControl is injected when the player is created.
An ExoPlayer can be built using the default components provided by the library, but may also be built using custom implementations if non-standard behaviors are required. For example a custom LoadControl could be injected to change the player's buffering strategy, or a custom Renderer could be injected to use a video codec not supported natively by Android.
The concept of injecting components that implement pieces of player functionality is present throughout the library. The default component implementations listed above delegate work to further injected components. This allows many sub-components to be individually replaced with custom implementations. For example the default MediaSource implementations require one or more DataSource factories to be injected via their constructors. By providing a custom factory it's possible to load data from a non-standard source or through a different network stack.
Threading model

The figure below shows ExoPlayer's threading model.
- It is recommended that ExoPlayer instances are created and accessed from a single application thread. The application's main thread is ideal. Accessing an instance from multiple threads is discouraged, however if an application does wish to do this then it may do so provided that it ensures accesses are synchronized.
- Registered listeners are called on the thread that created the ExoPlayer instance, unless the thread that created the ExoPlayer instance does not have a Looper. In that case, registered listeners will be called on the application's main thread.
- An internal playback thread is responsible for playback. Injected player components such as Renderers, MediaSources, TrackSelectors and LoadControls are called by the player on this thread.
- When the application performs an operation on the player, for example a seek, a message is delivered to the internal playback thread via a message queue. The internal playback thread consumes messages from the queue and performs the corresponding operations. Similarly, when a playback event occurs on the internal playback thread, a message is delivered to the application thread via a second message queue. The application thread consumes messages from the queue, updating the application visible state and calling corresponding listener methods.
- Injected player components may use additional background threads. For example a MediaSource may use a background thread to load data. These are implementation specific.

Nested Class Summary

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`ExoPlayer.EventListener` Listener of changes in player state.
`static interface`	`ExoPlayer.ExoPlayerComponent` A component of an `ExoPlayer` that can receive messages on the playback thread.
`static class`	`ExoPlayer.ExoPlayerMessage` Defines a message and a target `ExoPlayer.ExoPlayerComponent` to receive it.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`STATE_BUFFERING` The player not able to immediately play from the current position.
`static int`	`STATE_ENDED` The player has finished playing the media.
`static int`	`STATE_IDLE` The player does not have a source to play, so it is neither buffering nor ready to play.
`static int`	`STATE_READY` The player is able to immediately play from the current position.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addListener(ExoPlayer.EventListener listener)` Register a listener to receive events from the player.
`void`	`blockingSendMessages(ExoPlayer.ExoPlayerMessage... messages)` Variant of `sendMessages(ExoPlayerMessage...)` that blocks until after the messages have been delivered.
`int`	`getBufferedPercentage()` Returns an estimate of the percentage in the current window up to which data is buffered, or 0 if no estimate is available.
`long`	`getBufferedPosition()` Returns an estimate of the position in the current window up to which data is buffered, in milliseconds.
`java.lang.Object`	`getCurrentManifest()` Returns the current manifest.
`int`	`getCurrentPeriodIndex()` Returns the index of the period currently being played.
`long`	`getCurrentPosition()` Returns the playback position in the current window, in milliseconds.
`Timeline`	`getCurrentTimeline()` Returns the current `Timeline`.
`TrackGroupArray`	`getCurrentTrackGroups()` Returns the available track groups.
`TrackSelectionArray`	`getCurrentTrackSelections()` Returns the current track selections for each renderer.
`int`	`getCurrentWindowIndex()` Returns the index of the window currently being played.
`long`	`getDuration()` Returns the duration of the current window in milliseconds, or `C.TIME_UNSET` if the duration is not known.
`PlaybackParameters`	`getPlaybackParameters()` Returns the currently active playback parameters.
`int`	`getPlaybackState()` Returns the current state of the player.
`boolean`	`getPlayWhenReady()` Whether playback will proceed when `getPlaybackState()` == `STATE_READY`.
`int`	`getRendererCount()` Returns the number of renderers.
`int`	`getRendererType(int index)` Returns the track type that the renderer at a given index handles.
`boolean`	`isCurrentWindowDynamic()` Returns whether the current window is dynamic, or `false` if the `Timeline` is empty.
`boolean`	`isCurrentWindowSeekable()` Returns whether the current window is seekable, or `false` if the `Timeline` is empty.
`boolean`	`isLoading()` Whether the player is currently loading the source.
`void`	`prepare(MediaSource mediaSource)` Prepares the player to play the provided `MediaSource`.
`void`	`prepare(MediaSource mediaSource, boolean resetPosition, boolean resetState)` Prepares the player to play the provided `MediaSource`, optionally resetting the playback position the default position in the first `Timeline.Window`.
`void`	`release()` Releases the player.
`void`	`removeListener(ExoPlayer.EventListener listener)` Unregister a listener.
`void`	`seekTo(int windowIndex, long positionMs)` Seeks to a position specified in milliseconds in the specified window.
`void`	`seekTo(long positionMs)` Seeks to a position specified in milliseconds in the current window.
`void`	`seekToDefaultPosition()` Seeks to the default position associated with the current window.
`void`	`seekToDefaultPosition(int windowIndex)` Seeks to the default position associated with the specified window.
`void`	`sendMessages(ExoPlayer.ExoPlayerMessage... messages)` Sends messages to their target components.
`void`	`setPlaybackParameters(PlaybackParameters playbackParameters)` Attempts to set the playback parameters.
`void`	`setPlayWhenReady(boolean playWhenReady)` Sets whether playback should proceed when `getPlaybackState()` == `STATE_READY`.
`void`	`stop()` Stops playback.

- Field Detail
  - STATE_IDLE
```
static final int STATE_IDLE
```
    The player does not have a source to play, so it is neither buffering nor ready to play.
    
    See Also:
    
    Constant Field Values
  - STATE_BUFFERING
```
static final int STATE_BUFFERING
```
    The player not able to immediately play from the current position. The cause is Renderer specific, but this state typically occurs when more data needs to be loaded to be ready to play, or more data needs to be buffered for playback to resume.
    
    See Also:
    
    Constant Field Values
  - STATE_READY
```
static final int STATE_READY
```
    The player is able to immediately play from the current position. The player will be playing if getPlayWhenReady() returns true, and paused otherwise.
    
    See Also:
    
    Constant Field Values
  - STATE_ENDED
```
static final int STATE_ENDED
```
    The player has finished playing the media.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - addListener
```
void addListener(ExoPlayer.EventListener listener)
```
    Register a listener to receive events from the player. The listener's methods will be called on the thread that was used to construct the player. However, if the thread used to construct the player does not have a Looper, then the listener will be called on the main thread.
    
    Parameters:
    
    listener - The listener to register.
  - removeListener
```
void removeListener(ExoPlayer.EventListener listener)
```
    Unregister a listener. The listener will no longer receive events from the player.
    
    Parameters:
    
    listener - The listener to unregister.
  - getPlaybackState
```
int getPlaybackState()
```
    Returns the current state of the player.
    
    Returns:
    
    One of the STATE constants defined in this interface.
  - prepare
```
void prepare(MediaSource mediaSource)
```
    Prepares the player to play the provided MediaSource. Equivalent to prepare(mediaSource, true, true).
  - prepare
```
void prepare(MediaSource mediaSource,
             boolean resetPosition,
             boolean resetState)
```
    Prepares the player to play the provided MediaSource, optionally resetting the playback position the default position in the first Timeline.Window.
    
    Parameters:
    
    mediaSource - The MediaSource to play.
    
    resetPosition - Whether the playback position should be reset to the default position in the first Timeline.Window. If false, playback will start from the position defined by getCurrentWindowIndex() and getCurrentPosition().
    
    resetState - Whether the timeline, manifest, tracks and track selections should be reset. Should be true unless the player is being prepared to play the same media as it was playing previously (e.g. if playback failed and is being retried).
  - setPlayWhenReady
```
void setPlayWhenReady(boolean playWhenReady)
```
    Sets whether playback should proceed when getPlaybackState() == STATE_READY.
    If the player is already in the ready state then this method can be used to pause and resume playback.
    
    Parameters:
    
    playWhenReady - Whether playback should proceed when ready.
  - getPlayWhenReady
```
boolean getPlayWhenReady()
```
    Whether playback will proceed when getPlaybackState() == STATE_READY.
    
    Returns:
    
    Whether playback will proceed when ready.
  - isLoading
```
boolean isLoading()
```
    Whether the player is currently loading the source.
    
    Returns:
    
    Whether the player is currently loading the source.
  - seekToDefaultPosition
```
void seekToDefaultPosition()
```
    Seeks to the default position associated with the current window. The position can depend on the type of source passed to prepare(MediaSource). For live streams it will typically be the live edge of the window. For other streams it will typically be the start of the window.
  - seekToDefaultPosition
```
void seekToDefaultPosition(int windowIndex)
```
    Seeks to the default position associated with the specified window. The position can depend on the type of source passed to prepare(MediaSource). For live streams it will typically be the live edge of the window. For other streams it will typically be the start of the window.
    
    Parameters:
    
    windowIndex - The index of the window whose associated default position should be seeked to.
  - seekTo
```
void seekTo(long positionMs)
```
    Seeks to a position specified in milliseconds in the current window.
    
    Parameters:
    
    positionMs - The seek position in the current window, or C.TIME_UNSET to seek to the window's default position.
  - seekTo
```
void seekTo(int windowIndex,
            long positionMs)
```
    Seeks to a position specified in milliseconds in the specified window.
    
    Parameters:
    
    windowIndex - The index of the window.
    
    positionMs - The seek position in the specified window, or C.TIME_UNSET to seek to the window's default position.
  - setPlaybackParameters
```
void setPlaybackParameters(@Nullable
                           PlaybackParameters playbackParameters)
```
    Attempts to set the playback parameters. Passing null sets the parameters to the default, PlaybackParameters.DEFAULT, which means there is no speed or pitch adjustment.
    Playback parameters changes may cause the player to buffer. ExoPlayer.EventListener.onPlaybackParametersChanged(PlaybackParameters) will be called whenever the currently active playback parameters change. When that listener is called, the parameters passed to it may not match playbackParameters. For example, the chosen speed or pitch may be out of range, in which case they are constrained to a set of permitted values. If it is not possible to change the playback parameters, the listener will not be invoked.
    
    Parameters:
    
    playbackParameters - The playback parameters, or null to use the defaults.
  - getPlaybackParameters
```
PlaybackParameters getPlaybackParameters()
```
    Returns the currently active playback parameters.
    
    See Also:
    
    ExoPlayer.EventListener.onPlaybackParametersChanged(PlaybackParameters)
  - stop
```
void stop()
```
    Stops playback. Use setPlayWhenReady(false) rather than this method if the intention is to pause playback.
    Calling this method will cause the playback state to transition to STATE_IDLE. The player instance can still be used, and release() must still be called on the player if it's no longer required.
    Calling this method does not reset the playback position.
  - release
```
void release()
```
    Releases the player. This method must be called when the player is no longer required. The player must not be used after calling this method.
  - sendMessages
```
void sendMessages(ExoPlayer.ExoPlayerMessage... messages)
```
    Sends messages to their target components. The messages are delivered on the playback thread. If a component throws an ExoPlaybackException then it is propagated out of the player as an error.
    
    Parameters:
    
    messages - The messages to be sent.
  - blockingSendMessages
```
void blockingSendMessages(ExoPlayer.ExoPlayerMessage... messages)
```
    Variant of sendMessages(ExoPlayerMessage...) that blocks until after the messages have been delivered.
    
    Parameters:
    
    messages - The messages to be sent.
  - getRendererCount
```
int getRendererCount()
```
    Returns the number of renderers.
  - getRendererType
```
int getRendererType(int index)
```
    Returns the track type that the renderer at a given index handles.
    
    Parameters:
    
    index - The index of the renderer.
    
    Returns:
    
    One of the TRACK_TYPE_* constants defined in C.
    
    See Also:
    
    Renderer.getTrackType()
  - getCurrentTrackGroups
```
TrackGroupArray getCurrentTrackGroups()
```
    Returns the available track groups.
  - getCurrentTrackSelections
```
TrackSelectionArray getCurrentTrackSelections()
```
    Returns the current track selections for each renderer.
  - getCurrentManifest
```
java.lang.Object getCurrentManifest()
```
    Returns the current manifest. The type depends on the MediaSource passed to prepare(com.google.android.exoplayer2.source.MediaSource). May be null.
  - getCurrentTimeline
```
Timeline getCurrentTimeline()
```
    Returns the current Timeline. Never null, but may be empty.
  - getCurrentPeriodIndex
```
int getCurrentPeriodIndex()
```
    Returns the index of the period currently being played.
  - getCurrentWindowIndex
```
int getCurrentWindowIndex()
```
    Returns the index of the window currently being played.
  - getDuration
```
long getDuration()
```
    Returns the duration of the current window in milliseconds, or C.TIME_UNSET if the duration is not known.
  - getCurrentPosition
```
long getCurrentPosition()
```
    Returns the playback position in the current window, in milliseconds.
  - getBufferedPosition
```
long getBufferedPosition()
```
    Returns an estimate of the position in the current window up to which data is buffered, in milliseconds.
  - getBufferedPercentage
```
int getBufferedPercentage()
```
    Returns an estimate of the percentage in the current window up to which data is buffered, or 0 if no estimate is available.
  - isCurrentWindowDynamic
```
boolean isCurrentWindowDynamic()
```
    Returns whether the current window is dynamic, or false if the Timeline is empty.
    
    See Also:
    
    Timeline.Window.isDynamic
  - isCurrentWindowSeekable
```
boolean isCurrentWindowSeekable()
```
    Returns whether the current window is seekable, or false if the Timeline is empty.
    
    See Also:
    
    Timeline.Window.isSeekable

Interface ExoPlayer

Player composition

Threading model

Nested Class Summary

Field Summary

Method Summary

Field Detail

STATE_IDLE

STATE_BUFFERING

STATE_READY

STATE_ENDED

Method Detail

addListener

removeListener

getPlaybackState

prepare

prepare

setPlayWhenReady

getPlayWhenReady

isLoading

seekToDefaultPosition

seekToDefaultPosition

seekTo

seekTo

setPlaybackParameters

getPlaybackParameters

stop

release

sendMessages

blockingSendMessages

getRendererCount

getRendererType

getCurrentTrackGroups

getCurrentTrackSelections

getCurrentManifest

getCurrentTimeline

getCurrentPeriodIndex

getCurrentWindowIndex

getDuration

getCurrentPosition

getBufferedPosition

getBufferedPercentage

isCurrentWindowDynamic

isCurrentWindowSeekable