For simple use cases, getting started with
ExoPlayer consists of implementing
the following steps:
- Add ExoPlayer as a dependency to your project.
- Create an
- Attach the player to a view (for video output and user input).
- Prepare the player with a
- Release the player when done.
These steps are described in more detail below. For a complete example, refer to
PlayerActivity in the main demo app.
Add ExoPlayer as a dependency
Add ExoPlayer modules
The easiest way to get started using AndroidX Media3 is to add gradle
dependencies on the libraries you need in the
build.gradle file of your app
For example, to depend on ExoPlayer with DASH playback support and UI components you can add dependencies on the modules like this:
implementation("androidx.media3:media3-exoplayer:1.2.1") implementation("androidx.media3:media3-exoplayer-dash:1.2.1") implementation("androidx.media3:media3-ui:1.2.1")
implementation "androidx.media3:media3-exoplayer:1.2.1" implementation "androidx.media3:media3-exoplayer-dash:1.2.1" implementation "androidx.media3:media3-ui:1.2.1"
where 1.2.1 is your preferred version (the latest version can be found by consulting the release notes). All modules must be the same version.
AndroidX Media3 has library modules that depend on external libraries to provide additional functionality. Some are available from the Maven repository, whereas others must be built manually. Browse the libraries directory and see individual READMEs for details.
More information on the library modules that are available can be found on the Google Maven AndroidX Media page.
Turn on Java 8 support
If not enabled already, you need to turn on Java 8 support in all
files that depend on ExoPlayer, by adding the following to the
If your Gradle
minSdkVersion is 20 or lower, you should
enable multidex in order
to prevent build errors.
Create the player
You can create an
ExoPlayer instance using
ExoPlayer.Builder, which provides
a range of customization options. The following code is the simplest example of
creating an instance.
val player = ExoPlayer.Builder(context).build()
ExoPlayer player = new ExoPlayer.Builder(context).build();
A note on threading
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 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
specified, then the
Looper of the thread that the player is created on is
used, or if that thread does not have a
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
For more information about ExoPlayer's threading model, see the "Threading model" section of the ExoPlayer Javadoc.
Attach the player to a view
The ExoPlayer library provides a range of pre-built UI components for media
playback. These include
PlayerView, which encapsulates a
SubtitleView, and a
Surface onto which video is
PlayerView can be included in your application's layout xml.
For example, to bind the player to the view:
// Bind the player to the view. playerView.player = player
// Bind the player to the view. playerView.setPlayer(player);
You can also use
PlayerControlView as a standalone component, which is
useful for audio only use cases.
Use of ExoPlayer's pre-built UI components is optional. For video apps
that implement their own UI, the target
Surface can be set using ExoPlayer's
setVideoSurface methods respectively. ExoPlayer's
addTextOutput method can
be used to receive captions that should be rendered during playback.
Populate the playlist and preparing the player
In ExoPlayer, every piece of media is represented by a
MediaItem. To play a
piece of media, you need to build a corresponding
MediaItem, add it to the
player, prepare the player, and call
play to start the playback:
// Build the media item. val mediaItem = MediaItem.fromUri(videoUri) // Set the media item to be played. player.setMediaItem(mediaItem) // Prepare the player. player.prepare() // Start the playback. player.play()
// Build the media item. MediaItem mediaItem = MediaItem.fromUri(videoUri); // Set the media item to be played. player.setMediaItem(mediaItem); // Prepare the player. player.prepare(); // Start the playback. player.play();
ExoPlayer supports playlists directly, so it's possible to prepare the player with multiple media items to be played one after the other:
// Build the media items. val firstItem = MediaItem.fromUri(firstVideoUri) val secondItem = MediaItem.fromUri(secondVideoUri) // Add the media items to be played. player.addMediaItem(firstItem) player.addMediaItem(secondItem) // Prepare the player. player.prepare() // Start the playback. player.play()
// Build the media items. MediaItem firstItem = MediaItem.fromUri(firstVideoUri); MediaItem secondItem = MediaItem.fromUri(secondVideoUri); // Add the media items to be played. player.addMediaItem(firstItem); player.addMediaItem(secondItem); // Prepare the player. player.prepare(); // Start the playback. player.play();
The playlist can be updated during playback without the need to prepare the player again. Read more about populating and manipulating the playlist on the Playlists page. Read more about the different options available when building media items, such as clipping and attaching subtitle files, on the Media items page.
Control the player
Once the player has been prepared, playback can be controlled by calling methods on the player. Here are some of the most commonly used methods:
pausestart and pause playback.
seekToallows seeking within the media.
nextallow navigating through the playlist.
setRepeatModecontrols if and how media is looped.
setShuffleModeEnabledcontrols playlist shuffling.
setPlaybackParametersadjusts playback speed and audio pitch.
If the player is bound to a
then user interaction with these components will cause corresponding methods on
the player to be invoked.
Release the player
It's important to release the player when it's no longer needed, so as to free
up limited resources such as video decoders for use by other applications. This
can be done by calling