com.google.android.exoplayer2

Interface ExoPlayer

All Superinterfaces:

Player

All Known Implementing Classes:

SimpleExoPlayer

public interface ExoPlayer
extends Player

An extensible media player that plays MediaSources. Instances can be obtained from ExoPlayerFactory.

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 prepare(MediaSource) at the start of playback. The library modules provide default implementations for regular media files (ExtractorMediaSource), 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 and Description
static interface	ExoPlayer.EventListener Deprecated. Use Player.EventListener instead.
static interface	ExoPlayer.ExoPlayerComponent Deprecated. Use PlayerMessage.Target instead.
static class	ExoPlayer.ExoPlayerMessage Deprecated. Use PlayerMessage instead.

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

Player.AudioComponent, Player.DefaultEventListener, Player.DiscontinuityReason, Player.MetadataComponent, Player.RepeatMode, Player.TextComponent, Player.TimelineChangeReason, Player.VideoComponent

Field Summary

Fields

Modifier and Type	Field and Description
static int	REPEAT_MODE_ALL Deprecated. Use Player.REPEAT_MODE_ALL instead.
static int	REPEAT_MODE_OFF Deprecated. Use Player.REPEAT_MODE_OFF instead.
static int	REPEAT_MODE_ONE Deprecated. Use Player.REPEAT_MODE_ONE instead.
static int	STATE_BUFFERING Deprecated. Use Player.STATE_BUFFERING instead.
static int	STATE_ENDED Deprecated. Use Player.STATE_ENDED instead.
static int	STATE_IDLE Deprecated. Use Player.STATE_IDLE instead.
static int	STATE_READY Deprecated. Use Player.STATE_READY instead.

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, TIMELINE_CHANGE_REASON_DYNAMIC, TIMELINE_CHANGE_REASON_PREPARED, TIMELINE_CHANGE_REASON_RESET

Method Summary

Modifier and Type	Method and Description
void	blockingSendMessages(ExoPlayer.ExoPlayerMessage... messages) Deprecated. Use createMessage(PlayerMessage.Target) with PlayerMessage.blockUntilDelivered().
PlayerMessage	createMessage(PlayerMessage.Target target) Creates a message that can be sent to a PlayerMessage.Target.
android.os.Looper	getPlaybackLooper() Returns the Looper associated with the playback thread.
SeekParameters	getSeekParameters() Returns the currently active SeekParameters of the player.
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	retry() Retries a failed or stopped playback.
void	sendMessages(ExoPlayer.ExoPlayerMessage... messages) Deprecated. Use createMessage(PlayerMessage.Target) instead.
void	setSeekParameters(SeekParameters seekParameters) Sets the parameters that control how seek operations are performed.

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

addListener, getApplicationLooper, getAudioComponent, getBufferedPercentage, getBufferedPosition, getContentBufferedPosition, getContentDuration, getContentPosition, getCurrentAdGroupIndex, getCurrentAdIndexInAdGroup, getCurrentManifest, getCurrentPeriodIndex, getCurrentPosition, getCurrentTag, getCurrentTimeline, getCurrentTrackGroups, getCurrentTrackSelections, getCurrentWindowIndex, getDuration, getMetadataComponent, getNextWindowIndex, getPlaybackError, getPlaybackParameters, getPlaybackState, getPlayWhenReady, getPreviousWindowIndex, getRendererCount, getRendererType, getRepeatMode, getShuffleModeEnabled, getTextComponent, getTotalBufferedDuration, getVideoComponent, hasNext, hasPrevious, isCurrentWindowDynamic, isCurrentWindowSeekable, isLoading, isPlayingAd, next, previous, release, removeListener, seekTo, seekTo, seekToDefaultPosition, seekToDefaultPosition, setPlaybackParameters, setPlayWhenReady, setRepeatMode, setShuffleModeEnabled, stop, stop

Field Detail

STATE_IDLE

@Deprecated
static final int STATE_IDLE

Deprecated. Use Player.STATE_IDLE instead.

See Also:

Constant Field Values

STATE_BUFFERING

@Deprecated
static final int STATE_BUFFERING

Deprecated. Use Player.STATE_BUFFERING instead.

See Also:

Constant Field Values

STATE_READY

@Deprecated
static final int STATE_READY

Deprecated. Use Player.STATE_READY instead.

See Also:

Constant Field Values

STATE_ENDED

@Deprecated
static final int STATE_ENDED

Deprecated. Use Player.STATE_ENDED instead.

See Also:

Constant Field Values

REPEAT_MODE_OFF

@Deprecated
 @Player.RepeatMode
static final int REPEAT_MODE_OFF

Deprecated. Use Player.REPEAT_MODE_OFF instead.

See Also:

Constant Field Values

REPEAT_MODE_ONE

@Deprecated
 @Player.RepeatMode
static final int REPEAT_MODE_ONE

Deprecated. Use Player.REPEAT_MODE_ONE instead.

See Also:

Constant Field Values

REPEAT_MODE_ALL

@Deprecated
 @Player.RepeatMode
static final int REPEAT_MODE_ALL

Deprecated. Use Player.REPEAT_MODE_ALL instead.

See Also:

Constant Field Values

Method Detail

getPlaybackLooper

android.os.Looper getPlaybackLooper()

Returns the Looper associated with the playback thread.

retry

void retry()

Retries a failed or stopped playback. Does nothing if the player has been reset, or if playback has not failed or been stopped.

prepare

void prepare(MediaSource mediaSource)

Prepares the player to play the provided MediaSource. Equivalent to prepare(mediaSource, true, true).

Note: MediaSource instances are not designed to be re-used. If you want to prepare a player more than once with the same piece of media, use a new instance each time.

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.

Note: MediaSource instances are not designed to be re-used. If you want to prepare a player more than once with the same piece of media, use a new instance each time.

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 Player.getCurrentWindowIndex() and Player.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).

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).

sendMessages

@Deprecated
void sendMessages(ExoPlayer.ExoPlayerMessage... messages)

Deprecated. Use createMessage(PlayerMessage.Target) instead.

blockingSendMessages

@Deprecated
void blockingSendMessages(ExoPlayer.ExoPlayerMessage... messages)

Deprecated. Use createMessage(PlayerMessage.Target) with PlayerMessage.blockUntilDelivered().

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.