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, DynamicConcatenatingMediaSource, 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.

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

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

Player.DefaultEventListener, Player.DiscontinuityReason, Player.RepeatMode

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_INTERNAL, DISCONTINUITY_REASON_PERIOD_TRANSITION, DISCONTINUITY_REASON_SEEK, DISCONTINUITY_REASON_SEEK_ADJUSTMENT

Method Summary

Modifier and Type	Method and Description
void	blockingSendMessages(ExoPlayer.ExoPlayerMessage... messages) Variant of sendMessages(ExoPlayerMessage...) that blocks until after the messages have been delivered.
android.os.Looper	getPlaybackLooper() Gets the Looper associated with the playback thread.
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	sendMessages(ExoPlayer.ExoPlayerMessage... messages) Sends messages to their target components.

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

addListener, getBufferedPercentage, getBufferedPosition, getContentPosition, getCurrentAdGroupIndex, getCurrentAdIndexInAdGroup, getCurrentManifest, getCurrentPeriodIndex, getCurrentPosition, getCurrentTimeline, getCurrentTrackGroups, getCurrentTrackSelections, getCurrentWindowIndex, getDuration, getNextWindowIndex, getPlaybackParameters, getPlaybackState, getPlayWhenReady, getPreviousWindowIndex, getRendererCount, getRendererType, getRepeatMode, getShuffleModeEnabled, isCurrentWindowDynamic, isCurrentWindowSeekable, isLoading, isPlayingAd, release, removeListener, seekTo, seekTo, seekToDefaultPosition, seekToDefaultPosition, setPlaybackParameters, setPlayWhenReady, setRepeatMode, setShuffleModeEnabled, 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
static final int REPEAT_MODE_OFF

Deprecated. Use Player.REPEAT_MODE_OFF instead.

See Also:

Constant Field Values

REPEAT_MODE_ONE

@Deprecated
static final int REPEAT_MODE_ONE

Deprecated. Use Player.REPEAT_MODE_ONE instead.

See Also:

Constant Field Values

REPEAT_MODE_ALL

@Deprecated
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()

Gets the Looper associated with the playback thread.

Returns:

The Looper associated with the playback thread.

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

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.