Jetpack Media3 defines a`Player`interface that outlines basic functionality for playback of video and audio files.`ExoPlayer`is the default implementation of this interface in Media3. We recommend using ExoPlayer, as it provides a comprehensive set of features that cover most playback use-cases and is customizable to handle any additional use-cases you might have. ExoPlayer also abstracts away device and OS fragmentation so your code works consistently across the entire Android ecosystem. ExoPlayer includes:

- Support for[playlists](https://developer.android.com/guide/topics/media/exoplayer/playlists)
- Support for a variety of progressive and adaptive streaming[formats](https://developer.android.com/guide/topics/media/exoplayer/supported-formats)
- Support for both client-side and server-side[ad insertion](https://developer.android.com/guide/topics/media/exoplayer/ad-insertion)
- Support for[DRM-protected playback](https://developer.android.com/guide/topics/media/exoplayer/drm)

This page walks you through some of the key steps in building a playback app, and for more details you can head to our full guides on[Media3 ExoPlayer](https://developer.android.com/guide/topics/media/exoplayer).

## Getting started

To get started, add a dependency on the ExoPlayer, UI, and Common modules of Jetpack Media3:  

```groovy
implementation "androidx.media3:media3-exoplayer:1.8.0"
implementation "androidx.media3:media3-ui:1.8.0"
implementation "androidx.media3:media3-common:1.8.0"
```

Depending on your use-case, you may also need additional modules from Media3, such as`exoplayer-dash`to play streams in the DASH format.

Make sure to replace`1.8.0`with your preferred version of the library. You can refer to the[release notes](https://github.com/androidx/media/tree/release/RELEASENOTES.md)to see the latest version.

## Creating a media player

With Media3, you can either use the included implementation of the`Player`interface,`ExoPlayer`, or you can build your own custom implementation.

### Creating an ExoPlayer

The simplest way to create an`ExoPlayer`instance is as follows:  

### Kotlin

```kotlin
val player = ExoPlayer.Builder(context).build()
```

### Java

```java
ExoPlayer player = new ExoPlayer.Builder(context).build();
```

You can create your media player in the`onCreate()`lifecycle method of the`Activity`,`Fragment`, or`Service`where it lives.

The[`Builder`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer.Builder)includes a range of customization options you may be interested in, such as:

- [`setAudioAttributes()`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer.Builder#setAudioAttributes(androidx.media3.common.AudioAttributes,boolean))to configure[audio focus](https://developer.android.com/media/optimize/audio-focus)handling
- [`setHandleAudioBecomingNoisy()`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer.Builder#setHandleAudioBecomingNoisy(boolean))to configure playback behavior when an audio output device is disconnected
- [`setTrackSelector()`](https://developer.android.com/reference/androidx/media3/exoplayer/ExoPlayer.Builder#setTrackSelector(androidx.media3.exoplayer.trackselection.TrackSelector))to configure[track selection](https://developer.android.com/guide/topics/media/exoplayer/track-selection)

Media3 provides a`PlayerView`UI component that you can include in your app's layout file. This component encapsulates a`PlayerControlView`for playback controls,`SubtitleView`for displaying subtitles, and`Surface`for rendering video.

### Preparing the player

Add[media items](https://developer.android.com/guide/topics/media/exoplayer/media-items)to a playlist for playback with methods like[`setMediaItem()`](https://developer.android.com/reference/androidx/media3/common/Player#setMediaItem(androidx.media3.common.MediaItem))and[`addMediaItem()`](https://developer.android.com/reference/androidx/media3/common/Player#addMediaItem(androidx.media3.common.MediaItem)). Then, call[`prepare()`](https://developer.android.com/reference/androidx/media3/common/Player#prepare())to start loading media and acquire the necessary resources.

You shouldn't perform these steps before the app is in the foreground. If your player is in an`Activity`or`Fragment`, this means preparing the player in the`onStart()`lifecycle method on API level 24 and higher or the`onResume()`lifecycle method on API level 23 and below. For a player that's in a`Service`, you can prepare it in`onCreate()`. Refer to the[Exoplayer codelab](https://developer.android.com/codelabs/exoplayer-intro#playeractivity.kt_4)for an example of how to implement lifecycle methods.

### Control the player

After the player has been prepared, you can control playback by calling methods on the player such as:

- [`play()`](https://developer.android.com/reference/androidx/media3/common/Player#play())and[`pause()`](https://developer.android.com/reference/androidx/media3/common/Player#pause())to start and pause playback
- [`seekTo()`](https://developer.android.com/reference/androidx/media3/common/Player#seekTo(long))to seek to a position within the current media item
- [`seekToNextMediaItem()`](https://developer.android.com/reference/androidx/media3/common/Player#seekToNextMediaItem())and[`seekToPreviousMediaItem()`](https://developer.android.com/reference/androidx/media3/common/Player#seekToPreviousMediaItem())to navigate through the playlist

UI components such as the`PlayerView`or`PlayerControlView`will update accordingly when bound to a player.

### Release the player

Playback can require resources that are in limited supply, such as video decoders, so it's important to call[`release()`](https://developer.android.com/reference/androidx/media3/common/Player#release())on your player to free up resources when the player is no longer needed.

If your player is in an`Activity`or`Fragment`, release the player in the`onStop()`lifecycle method on API level 24 and higher or the`onPause()`method on API level 23 and below. For a player that's in a`Service`, you can release it in`onDestroy()`. Refer to the[Exoplayer codelab](https://developer.android.com/codelabs/exoplayer-intro#playeractivity.kt_6)for an example of how to implement lifecycle methods.

## Managing playback with a media session

On Android, media sessions provide a standardized way to interact with a media player across process boundaries. Connecting a media session to your player allows you to advertise your media playback externally and to receive playback commands from external sources, for example to integrate with[system media controls](https://developer.android.com/media/implement/surfaces/mobile)on mobile and large screen devices.

To use media sessions, add a dependency on the Media3 Session module:  

```groovy
implementation "androidx.media3:media3-session:1.8.0"
```

### Create a media session

You can create a`MediaSession`after initializing a player as follows:  

### Kotlin

```kotlin
val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()
```

### Java

```java
ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();
```

Media3 automatically syncs the state of the`Player`with the state of the`MediaSession`. This works with any`Player`implementation, including`ExoPlayer`,[`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer), or a custom implementation.

### Grant control to other clients

Client apps can implement a[media controller](https://developer.android.com/reference/androidx/media3/session/MediaController)to control playback of your media session. To receive these requests, set a[callback](https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback)object when building your`MediaSession`.

When a controller is about to connect to your media session, the[`onConnect()`](https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onConnect(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo))method is called. You can use the provided[`ControllerInfo`](https://developer.android.com/reference/androidx/media3/session/MediaSession.ControllerInfo)to decide whether to[accept](https://developer.android.com/reference/androidx/media3/session/MediaSession.ConnectionResult#accept(androidx.media3.session.SessionCommands,androidx.media3.common.Player.Commands))or[reject](https://developer.android.com/reference/androidx/media3/session/MediaSession.ConnectionResult#reject())the request. See an example of this in the[Media3 Session demo app](https://github.com/androidx/media/blob/release/demos/session/src/main/java/androidx/media3/demo/session/PlaybackService.kt#L104).

Once connected, a controller can send playback commands to the session. The session then delegates those commands down to the player. Playback and playlist commands defined in the`Player`interface are automatically handled by the session.

Other callback methods allow you to handle, for example, requests for[custom playback commands](https://developer.android.com/guide/topics/media/media3/getting-started/mediasession#adding-custom)and[modifying the playlist](https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onAddMediaItems(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo,java.util.List%3Candroidx.media3.common.MediaItem%3E)). These callbacks similarly include a`ControllerInfo`object so you can determine access control on a request-by-request basis.
| **Note:** If you want to allow controllers to add media items to the player, implement the[`onAddMediaItems()`](https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback#onAddMediaItems(androidx.media3.session.MediaSession,androidx.media3.session.MediaSession.ControllerInfo,java.util.List%3Candroidx.media3.common.MediaItem%3E))callback. In addition to handling`setMediaItems()`and`addMediaItems()`requests from a Media3`MediaController`, this method is backward compatible with legacy APIs such as`TransportControls.prepareFrom*`and`TransportControls.playFrom*`. A sample implementation of`onAddMediaItems()`can be found in the[`PlaybackService`](https://github.com/androidx/media/blob/main/demos/session/src/main/java/androidx/media3/demo/session/PlaybackService.kt#L205)of the session demo app.

## Playing media in the background

To continue playing media when your app is not in the foreground, for example to play music, audiobooks, or podcasts even when the user doesn't have your app open, your`Player`and`MediaSession`should be encapsulated in a[foreground service](https://developer.android.com/develop/background-work/services/fgs). Media3 provides the`MediaSessionService`interface for this purpose.

### Implementing a`MediaSessionService`

Create a class that extends`MediaSessionService`and instantiate your`MediaSession`in the`onCreate()`lifecycle method.  

### Kotlin

```kotlin
class PlaybackService : MediaSessionService() {
    private var mediaSession: MediaSession? = null

    // Create your Player and MediaSession in the onCreate lifecycle event
    override fun onCreate() {
        super.onCreate()
        val player = ExoPlayer.Builder(this).build()
        mediaSession = MediaSession.Builder(this, player).build()
    }

    // Remember to release the player and media session in onDestroy
    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
            mediaSession = null
        }
        super.onDestroy()
    }
}
```

### Java

```java
public class PlaybackService extends MediaSessionService {
    private MediaSession mediaSession = null;

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

    @Override
    public void onDestroy() {
        mediaSession.getPlayer().release();
        mediaSession.release();
        mediaSession = null;
        super.onDestroy();
    }
}
```

In your manifest, add your`Service`class with a`MediaSessionService`intent filter and request the`FOREGROUND_SERVICE`permission to run a foreground service:  

    <service
        android:name=".PlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaSessionService"/>
        </intent-filter>
    </service>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Lastly, in the class you created, override the`onGetSession()`method to control client access to your media session. Return a`MediaSession`to accept the connection request, or return`null`to reject the request.  

### Kotlin

```kotlin
// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession
```

### Java

```java
@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}
```

### Connecting to your UI

Now that your media session is in a`Service`separate from the`Activity`or`Fragment`where your player UI lives, you can use a`MediaController`to link them together. In the`onStart()`method of the`Activity`or`Fragment`with your UI, create a`SessionToken`for your`MediaSession`, then use the`SessionToken`to build a`MediaController`. Building a`MediaController`happens asynchronously.  

### Kotlin

```kotlin
override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}
```

### Java

```java
@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}
```

`MediaController`implements the`Player`interface, so you can use the same methods such as`play()`and`pause()`to control playback. Similar to other components, remember to release the`MediaController`when it is no longer needed, such as the`onStop()`lifecycle method of an`Activity`, by calling[`MediaController.releaseFuture()`](https://developer.android.com/reference/androidx/media3/session/MediaController#releaseFuture(java.util.concurrent.Future%3C?%20extends%20androidx.media3.session.MediaController%3E)).

### Publishing a notification

Foreground services are required to publish a notification while active. A`MediaSessionService`will automatically create a[`MediaStyle`notification](https://developer.android.com/reference/android/app/Notification.MediaStyle)for you in the form of a[`MediaNotification`](https://developer.android.com/reference/androidx/media3/session/MediaNotification). To provide a custom notification, create a[`MediaNotification.Provider`](https://developer.android.com/reference/androidx/media3/session/MediaNotification.Provider)with[`DefaultMediaNotificationProvider.Builder`](https://developer.android.com/reference/androidx/media3/session/DefaultMediaNotificationProvider)or by creating a custom implementation of the provider interface. Add your provider to your`MediaSession`with[`setMediaNotificationProvider`](https://developer.android.com/reference/androidx/media3/session/MediaSessionService#setMediaNotificationProvider(androidx.media3.session.MediaNotification.Provider)).

## Advertising your content library

A`MediaLibraryService`builds on a`MediaSessionService`by allowing client apps to browse the media content provided by your app. Client apps implement a[`MediaBrowser`](https://developer.android.com/reference/androidx/media3/session/MediaBrowser)to interact with your`MediaLibraryService`.

Implementing a`MediaLibraryService`is similar to implementing a`MediaSessionService`, except that in`onGetSession()`you should return a`MediaLibrarySession`instead of a`MediaSession`. Compared to a`MediaSession.Callback`, the`MediaLibrarySession.Callback`includes additional methods that allow a browser client to navigate the content offered by your library service.

Similar to the`MediaSessionService`, declare the`MediaLibraryService`in your manifest and request the`FOREGROUND_SERVICE`permission to run a foreground service:  

    <service
        android:name=".PlaybackService"
        android:foregroundServiceType="mediaPlayback"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.media3.session.MediaLibraryService"/>
            <action android:name="android.media.browse.MediaBrowserService"/>
        </intent-filter>
    </service>

    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

The example above includes an intent filter for both the`MediaLibraryService`and, for backward compatibility, the legacy`MediaBrowserService`. The additional intent filter enables client apps using the`MediaBrowserCompat`API to recognize your`Service`.

A`MediaLibrarySession`lets you serve your content library in a tree structure, with a single root`MediaItem`. Each`MediaItem`in the tree can have any number of children`MediaItem`nodes. You can serve a different root, or a different tree, based on the client app's request. For example, the tree you return to a client looking for a list of recommended media items might only contain the root`MediaItem`and a single level of children`MediaItem`nodes, whereas the tree you return to a different client app may represent a more complete library of content.

### Creating a`MediaLibrarySession`

A[`MediaLibrarySession`](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.MediaLibrarySession)extends the`MediaSession`API to add content browsing APIs. Compared to the[`MediaSession`callback](https://developer.android.com/reference/androidx/media3/session/MediaSession.Callback), the[`MediaLibrarySession`callback](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.MediaLibrarySession.Callback)adds methods such as:

- [`onGetLibraryRoot()`](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.MediaLibrarySession.Callback#onGetLibraryRoot(androidx.media3.session.MediaLibraryService.MediaLibrarySession,androidx.media3.session.MediaSession.ControllerInfo,androidx.media3.session.MediaLibraryService.LibraryParams))for when a client requests the root`MediaItem`of a content tree
- [`onGetChildren()`](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.MediaLibrarySession.Callback#onGetChildren(androidx.media3.session.MediaLibraryService.MediaLibrarySession,androidx.media3.session.MediaSession.ControllerInfo,java.lang.String,int,int,androidx.media3.session.MediaLibraryService.LibraryParams))for when a client requests the children of a`MediaItem`in the content tree
- [`onGetSearchResult()`](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.MediaLibrarySession.Callback#onGetSearchResult(androidx.media3.session.MediaLibraryService.MediaLibrarySession,androidx.media3.session.MediaSession.ControllerInfo,java.lang.String,int,int,androidx.media3.session.MediaLibraryService.LibraryParams))for when a client requests search results from the content tree for a given query

Relevant callback methods will include a[`LibraryParams`](https://developer.android.com/reference/androidx/media3/session/MediaLibraryService.LibraryParams)object with additional signals about the type of content tree that a client app is interested in.