ExoPlayer (ExoPlayer library)

All Superinterfaces:

Player

All Known Implementing Classes:

SimpleExoPlayer, StubExoPlayer
```
public interface ExoPlayer
extends Player
```
An extensible media player that plays MediaSources. Instances can be obtained from SimpleExoPlayer.Builder or ExoPlayer.Builder.
Player components

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 setMediaSource(MediaSource) at the start of playback. The library modules provide default implementations for progressive media files (ProgressiveMediaSource), DASH (DashMediaSource), SmoothStreaming (SsMediaSource) and HLS (HlsMediaSource), an implementation for loading single media samples (SingleSampleMediaSource) that's most often used for side-loaded subtitle files, and implementations for building more complex MediaSources from simpler ones (MergingMediaSource, ConcatenatingMediaSource, LoopingMediaSource and ClippingMediaSource).
- 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 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 add support for 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.
- ExoPlayer instances must be accessed from a single application thread. For the vast majority of cases this should be the application's main thread. Using the application's main thread is also a requirement when using ExoPlayer's UI components or the IMA extension. The thread on which an ExoPlayer instance must be accessed can be explicitly specified by passing a `Looper` when creating the player. If no `Looper` is specified, then the `Looper` of the thread that the player is created on is used, or if that thread does not have a `Looper`, the `Looper` of the application's main thread is used. In all cases the `Looper` of the thread from which the player must be accessed can be queried using Player.getApplicationLooper().
- Registered listeners are called on the thread associated with Player.getApplicationLooper(). Note that this means registered listeners are called on the same thread which must be used to access the player.
- 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 background threads to load data. These are implementation specific.

Nested Class Summary

Nested Classes
Modifier and Type Interface Description

static class ExoPlayer.Builder
A builder for ExoPlayer instances.
- Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Player
  Player.AudioComponent, Player.DefaultEventListener, Player.DeviceComponent, Player.DiscontinuityReason, Player.EventFlags, Player.EventListener, Player.Events, Player.MediaItemTransitionReason, Player.MetadataComponent, Player.PlaybackSuppressionReason, Player.PlayWhenReadyChangeReason, Player.RepeatMode, Player.State, Player.TextComponent, Player.TimelineChangeReason, Player.VideoComponent

Nested Classes
Modifier and Type	Interface	Description
`static class`	`ExoPlayer.Builder`	A builder for `ExoPlayer` instances.

Field Summary

Fields
Modifier and Type Field Description

static long DEFAULT_RELEASE_TIMEOUT_MS
The default timeout for calls to Player.release() and setForegroundMode(boolean), in milliseconds.
- Fields inherited from interface com.google.android.exoplayer2.Player
  DISCONTINUITY_REASON_AD_INSERTION, DISCONTINUITY_REASON_INTERNAL, DISCONTINUITY_REASON_PERIOD_TRANSITION, DISCONTINUITY_REASON_SEEK, DISCONTINUITY_REASON_SEEK_ADJUSTMENT, EVENT_IS_LOADING_CHANGED, EVENT_IS_PLAYING_CHANGED, EVENT_MEDIA_ITEM_TRANSITION, EVENT_PLAY_WHEN_READY_CHANGED, EVENT_PLAYBACK_PARAMETERS_CHANGED, EVENT_PLAYBACK_STATE_CHANGED, EVENT_PLAYBACK_SUPPRESSION_REASON_CHANGED, EVENT_PLAYER_ERROR, EVENT_POSITION_DISCONTINUITY, EVENT_REPEAT_MODE_CHANGED, EVENT_SHUFFLE_MODE_ENABLED_CHANGED, EVENT_STATIC_METADATA_CHANGED, EVENT_TIMELINE_CHANGED, EVENT_TRACKS_CHANGED, MEDIA_ITEM_TRANSITION_REASON_AUTO, MEDIA_ITEM_TRANSITION_REASON_PLAYLIST_CHANGED, MEDIA_ITEM_TRANSITION_REASON_REPEAT, MEDIA_ITEM_TRANSITION_REASON_SEEK, PLAY_WHEN_READY_CHANGE_REASON_AUDIO_BECOMING_NOISY, PLAY_WHEN_READY_CHANGE_REASON_AUDIO_FOCUS_LOSS, PLAY_WHEN_READY_CHANGE_REASON_END_OF_MEDIA_ITEM, PLAY_WHEN_READY_CHANGE_REASON_REMOTE, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST, PLAYBACK_SUPPRESSION_REASON_NONE, PLAYBACK_SUPPRESSION_REASON_TRANSIENT_AUDIO_FOCUS_LOSS, REPEAT_MODE_ALL, REPEAT_MODE_OFF, REPEAT_MODE_ONE, STATE_BUFFERING, STATE_ENDED, STATE_IDLE, STATE_READY, TIMELINE_CHANGE_REASON_PLAYLIST_CHANGED, TIMELINE_CHANGE_REASON_SOURCE_UPDATE

Fields
Modifier and Type	Field	Description
`static long`	`DEFAULT_RELEASE_TIMEOUT_MS`	The default timeout for calls to `Player.release()` and `setForegroundMode(boolean)`, in milliseconds.

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`addMediaSource(int index, MediaSource mediaSource)`	Adds a media source at the given index of the playlist.
`void`	`addMediaSource(MediaSource mediaSource)`	Adds a media source to the end of the playlist.
`void`	`addMediaSources(int index, List<MediaSource> mediaSources)`	Adds a list of media sources at the given index of the playlist.
`void`	`addMediaSources(List<MediaSource> mediaSources)`	Adds a list of media sources to the end of the playlist.
`PlayerMessage`	`createMessage(PlayerMessage.Target target)`	Creates a message that can be sent to a `PlayerMessage.Target`.
`boolean`	`experimentalIsSleepingForOffload()`	Returns whether the player has paused its main loop to save power in offload scheduling mode.
`void`	`experimentalSetOffloadSchedulingEnabled(boolean offloadSchedulingEnabled)`	Sets whether audio offload scheduling is enabled.
`Clock`	`getClock()`	Returns the `Clock` used for playback.
`boolean`	`getPauseAtEndOfMediaItems()`	Returns whether the player pauses playback at the end of each media item.
`Looper`	`getPlaybackLooper()`	Returns the `Looper` associated with the playback thread.
`SeekParameters`	`getSeekParameters()`	Returns the currently active `SeekParameters` of the player.
`TrackSelector`	`getTrackSelector()`	Returns the track selector that this player uses, or null if track selection is not supported.
`void`	`prepare(MediaSource mediaSource)`	Deprecated. Use `setMediaSource(MediaSource)` and `Player.prepare()` instead.
`void`	`prepare(MediaSource mediaSource, boolean resetPosition, boolean resetState)`	Deprecated. Use `setMediaSource(MediaSource, boolean)` and `Player.prepare()` instead.
`void`	`retry()`	Deprecated. Use `Player.prepare()` instead.
`void`	`setForegroundMode(boolean foregroundMode)`	Sets whether the player is allowed to keep holding limited resources such as video decoders, even when in the idle state.
`void`	`setMediaSource(MediaSource mediaSource)`	Clears the playlist, adds the specified `MediaSource` and resets the position to the default position.
`void`	`setMediaSource(MediaSource mediaSource, boolean resetPosition)`	Clears the playlist and adds the specified `MediaSource`.
`void`	`setMediaSource(MediaSource mediaSource, long startPositionMs)`	Clears the playlist and adds the specified `MediaSource`.
`void`	`setMediaSources(List<MediaSource> mediaSources)`	Clears the playlist, adds the specified `MediaSources` and resets the position to the default position.
`void`	`setMediaSources(List<MediaSource> mediaSources, boolean resetPosition)`	Clears the playlist and adds the specified `MediaSources`.
`void`	`setMediaSources(List<MediaSource> mediaSources, int startWindowIndex, long startPositionMs)`	Clears the playlist and adds the specified `MediaSources`.
`void`	`setPauseAtEndOfMediaItems(boolean pauseAtEndOfMediaItems)`	Sets whether to pause playback at the end of each media item.
`void`	`setSeekParameters(SeekParameters seekParameters)`	Sets the parameters that control how seek operations are performed.
`void`	`setShuffleOrder(ShuffleOrder shuffleOrder)`	Sets the shuffle order.

Methods inherited from interface com.google.android.exoplayer2.Player
addListener, addMediaItem, addMediaItem, addMediaItems, addMediaItems, clearMediaItems, getApplicationLooper, getAudioComponent, getBufferedPercentage, getBufferedPosition, getContentBufferedPosition, getContentDuration, getContentPosition, getCurrentAdGroupIndex, getCurrentAdIndexInAdGroup, getCurrentLiveOffset, getCurrentManifest, getCurrentMediaItem, getCurrentPeriodIndex, getCurrentPosition, getCurrentStaticMetadata, getCurrentTag, getCurrentTimeline, getCurrentTrackGroups, getCurrentTrackSelections, getCurrentWindowIndex, getDeviceComponent, getDuration, getMediaItemAt, getMediaItemCount, getMetadataComponent, getNextWindowIndex, getPlaybackError, getPlaybackParameters, getPlaybackState, getPlaybackSuppressionReason, getPlayerError, getPlayWhenReady, getPreviousWindowIndex, getRendererCount, getRendererType, getRepeatMode, getShuffleModeEnabled, getTextComponent, getTotalBufferedDuration, getVideoComponent, hasNext, hasPrevious, isCurrentWindowDynamic, isCurrentWindowLive, isCurrentWindowSeekable, isLoading, isPlaying, isPlayingAd, moveMediaItem, moveMediaItems, next, pause, play, prepare, previous, release, removeListener, removeMediaItem, removeMediaItems, seekTo, seekTo, seekToDefaultPosition, seekToDefaultPosition, setMediaItem, setMediaItem, setMediaItem, setMediaItems, setMediaItems, setMediaItems, setPlaybackParameters, setPlayWhenReady, setRepeatMode, setShuffleModeEnabled, stop, stop

- Field Detail
  - DEFAULT_RELEASE_TIMEOUT_MS
```
static final long DEFAULT_RELEASE_TIMEOUT_MS
```
    The default timeout for calls to Player.release() and setForegroundMode(boolean), in milliseconds.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getTrackSelector
```
@Nullable
TrackSelector getTrackSelector()
```
    Returns the track selector that this player uses, or null if track selection is not supported.
  - getPlaybackLooper
```
Looper getPlaybackLooper()
```
    Returns the Looper associated with the playback thread.
  - getClock
```
Clock getClock()
```
    Returns the Clock used for playback.
  - retry
```
@Deprecated
void retry()
```
    Deprecated.
    Use Player.prepare() instead.
  - prepare
```
@Deprecated
void prepare(MediaSource mediaSource)
```
    Deprecated.
    Use setMediaSource(MediaSource) and Player.prepare() instead.
  - prepare
```
@Deprecated
void prepare(MediaSource mediaSource,
             boolean resetPosition,
             boolean resetState)
```
    Deprecated.
    Use setMediaSource(MediaSource, boolean) and Player.prepare() instead.
  - setMediaSources
```
void setMediaSources(List<MediaSource> mediaSources)
```
    Clears the playlist, adds the specified MediaSources and resets the position to the default position.
    
    Parameters:
    
    mediaSources - The new MediaSources.
  - setMediaSources
```
void setMediaSources(List<MediaSource> mediaSources,
                     boolean resetPosition)
```
    Clears the playlist and adds the specified MediaSources.
    
    Parameters:
    
    mediaSources - The new MediaSources.
    
    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 Player.getCurrentWindowIndex() and Player.getCurrentPosition().
  - setMediaSources
```
void setMediaSources(List<MediaSource> mediaSources,
                     int startWindowIndex,
                     long startPositionMs)
```
    Clears the playlist and adds the specified MediaSources.
    
    Parameters:
    
    mediaSources - The new MediaSources.
    
    startWindowIndex - The window index to start playback from. If C.INDEX_UNSET is passed, the current position is not reset.
    
    startPositionMs - The position in milliseconds to start playback from. If C.TIME_UNSET is passed, the default position of the given window is used. In any case, if startWindowIndex is set to C.INDEX_UNSET, this parameter is ignored and the position is not reset at all.
  - setMediaSource
```
void setMediaSource(MediaSource mediaSource)
```
    Clears the playlist, adds the specified MediaSource and resets the position to the default position.
    
    Parameters:
    
    mediaSource - The new MediaSource.
  - setMediaSource
```
void setMediaSource(MediaSource mediaSource,
                    long startPositionMs)
```
    Clears the playlist and adds the specified MediaSource.
    
    Parameters:
    
    mediaSource - The new MediaSource.
    
    startPositionMs - The position in milliseconds to start playback from.
  - setMediaSource
```
void setMediaSource(MediaSource mediaSource,
                    boolean resetPosition)
```
    Clears the playlist and adds the specified MediaSource.
    
    Parameters:
    
    mediaSource - The new MediaSource.
    
    resetPosition - Whether the playback position should be reset to the default position. If false, playback will start from the position defined by Player.getCurrentWindowIndex() and Player.getCurrentPosition().
  - addMediaSource
```
void addMediaSource(MediaSource mediaSource)
```
    Adds a media source to the end of the playlist.
    
    Parameters:
    
    mediaSource - The MediaSource to add.
  - addMediaSource
```
void addMediaSource(int index,
                    MediaSource mediaSource)
```
    Adds a media source at the given index of the playlist.
    
    Parameters:
    
    index - The index at which to add the source.
    
    mediaSource - The MediaSource to add.
  - addMediaSources
```
void addMediaSources(List<MediaSource> mediaSources)
```
    Adds a list of media sources to the end of the playlist.
    
    Parameters:
    
    mediaSources - The MediaSources to add.
  - addMediaSources
```
void addMediaSources(int index,
                     List<MediaSource> mediaSources)
```
    Adds a list of media sources at the given index of the playlist.
    
    Parameters:
    
    index - The index at which to add the media sources.
    
    mediaSources - The MediaSources to add.
  - setShuffleOrder
```
void setShuffleOrder(ShuffleOrder shuffleOrder)
```
    Sets the shuffle order.
    
    Parameters:
    
    shuffleOrder - The shuffle order.
  - createMessage
```
PlayerMessage createMessage(PlayerMessage.Target target)
```
    Creates a message that can be sent to a PlayerMessage.Target. By default, the message will be delivered immediately without blocking on the playback thread. The default PlayerMessage.getType() is 0 and the default PlayerMessage.getPayload() is null. If a position is specified with PlayerMessage.setPosition(long), the message will be delivered at this position in the current window defined by Player.getCurrentWindowIndex(). Alternatively, the message can be sent at a specific window using PlayerMessage.setPosition(int, long).
  - setSeekParameters
```
void setSeekParameters(@Nullable
                       SeekParameters seekParameters)
```
    Sets the parameters that control how seek operations are performed.
    
    Parameters:
    
    seekParameters - The seek parameters, or null to use the defaults.
  - getSeekParameters
```
SeekParameters getSeekParameters()
```
    Returns the currently active SeekParameters of the player.
  - setForegroundMode
```
void setForegroundMode(boolean foregroundMode)
```
    Sets whether the player is allowed to keep holding limited resources such as video decoders, even when in the idle state. By doing so, the player may be able to reduce latency when starting to play another piece of content for which the same resources are required.
    This mode should be used with caution, since holding limited resources may prevent other players of media components from acquiring them. It should only be enabled when both of the following conditions are true:
    - The application that owns the player is in the foreground.
    - The player is used in a way that may benefit from foreground mode. For this to be true, the same player instance must be used to play multiple pieces of content, and there must be gaps between the playbacks (i.e. Player.stop() is called to halt one playback, and prepare(com.google.android.exoplayer2.source.MediaSource) is called some time later to start a new one).
    Note that foreground mode is not useful for switching between content without gaps between the playbacks. For this use case Player.stop() does not need to be called, and simply calling prepare(com.google.android.exoplayer2.source.MediaSource) for the new media will cause limited resources to be retained even if foreground mode is not enabled.
    If foreground mode is enabled, it's the application's responsibility to disable it when the conditions described above no longer hold.
    Parameters:
    
    foregroundMode - Whether the player is allowed to keep limited resources even when in the idle state.
  - setPauseAtEndOfMediaItems
```
void setPauseAtEndOfMediaItems(boolean pauseAtEndOfMediaItems)
```
    Sets whether to pause playback at the end of each media item.
    This means the player will pause at the end of each window in the current timeline. Listeners will be informed by a call to Player.EventListener.onPlayWhenReadyChanged(boolean, int) with the reason Player.PLAY_WHEN_READY_CHANGE_REASON_END_OF_MEDIA_ITEM when this happens.
    
    Parameters:
    
    pauseAtEndOfMediaItems - Whether to pause playback at the end of each media item.
  - getPauseAtEndOfMediaItems
```
boolean getPauseAtEndOfMediaItems()
```
    Returns whether the player pauses playback at the end of each media item.
    
    See Also:
    
    setPauseAtEndOfMediaItems(boolean)
  - experimentalSetOffloadSchedulingEnabled
```
void experimentalSetOffloadSchedulingEnabled(boolean offloadSchedulingEnabled)
```
    Sets whether audio offload scheduling is enabled. If enabled, ExoPlayer's main loop will run as rarely as possible when playing an audio stream using audio offload.
    Only use this scheduling mode if the player is not displaying anything to the user. For example when the application is in the background, or the screen is off. The player state (including position) is rarely updated (roughly between every 10 seconds and 1 minute).
    While offload scheduling is enabled, player events may be delivered severely delayed and apps should not interact with the player. When returning to the foreground, disable offload scheduling and wait for Player.EventListener.onExperimentalOffloadSchedulingEnabledChanged(boolean) to be called with offloadSchedulingEnabled = false before interacting with the player.
    This mode should save significant power when the phone is playing offload audio with the screen off.
    This mode only has an effect when playing an audio track in offload mode, which requires all the following:
    - Audio offload rendering is enabled in DefaultRenderersFactory.setEnableAudioOffload(boolean) or the equivalent option passed to DefaultAudioSink(AudioCapabilities, DefaultAudioSink.AudioProcessorChain, boolean, boolean, boolean).
    - An audio track is playing in a format that the device supports offloading (for example, MP3 or AAC).
    - The AudioSink is playing with an offload AudioTrack.
    The state where ExoPlayer main loop has been paused to save power during offload playback can be queried with experimentalIsSleepingForOffload().
    This method is experimental, and will be renamed or removed in a future release.
    Parameters:
    
    offloadSchedulingEnabled - Whether to enable offload scheduling.
  - experimentalIsSleepingForOffload
```
boolean experimentalIsSleepingForOffload()
```
    Returns whether the player has paused its main loop to save power in offload scheduling mode.
    
    See Also:
    
    experimentalSetOffloadSchedulingEnabled(boolean), Player.EventListener.onExperimentalSleepingForOffloadChanged(boolean)

Interface ExoPlayer

Player components

Threading model

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Player

Field Summary

Fields inherited from interface com.google.android.exoplayer2.Player

Method Summary

Methods inherited from interface com.google.android.exoplayer2.Player

Field Detail

DEFAULT_RELEASE_TIMEOUT_MS

Method Detail

getTrackSelector

getPlaybackLooper

getClock

retry

prepare

prepare

setMediaSources

setMediaSources

setMediaSources

setMediaSource

setMediaSource

setMediaSource

addMediaSource

addMediaSource

addMediaSources

addMediaSources

setShuffleOrder

createMessage

setSeekParameters

getSeekParameters

setForegroundMode

setPauseAtEndOfMediaItems

getPauseAtEndOfMediaItems

experimentalSetOffloadSchedulingEnabled

experimentalIsSleepingForOffload