Play media in the background
It is often desirable to play media while an app is not in the foreground. For example, a music player generally keeps playing music when the user has locked their device or is using another app. Similarly, a video player may want to enable a picture-in-picture mode. This is playing in the background.
The Media3 library provides a series of interfaces that allow you to support background playback in Android more easily than ever.
Use a MediaSessionService
To enable background playback, you should contain the Player
and
MediaSession
inside a separate Service. This allows the device to
continue serving media even while your app is not in the foreground.

When hosting a player inside a Service, you should use a MediaSessionService
.
To do this, create a class that extends MediaSessionService and create your
media session inside of it.
Using MediaSessionService
makes it easy for companion devices like Assistant,
System media controls or companion devices like Wear OS to discover your
service, connect to it, and control playback, all without accessing your app's
UI activity at all. In fact, there can be multiple apps connected to the same
MediaSessionService
at the same time, each app with its own MediaController
.
Provide access to the media session
Override the onGetSession()
method to give other clients access to your
media session.
// Extend MediaSessionService
class PlaybackService : MediaSessionService() {
// Create your Player and MediaSession in the onCreate lifecycle event
private lateinit var player: Player
private lateinit var mediaSession: MediaSession
override fun onCreate() {
super.onCreate()
player = ExoPlayer.Builder(this).build()
mediaSession = MediaSession.Builder(this, player).build()
}
// Return a MediaSession to link with the MediaController that is making
// this request.
override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaSession? = mediaSession
}
You must also declare your Service
class in the manifest with an intent filter
of MediaSessionService
.
<service
android:name=".PlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="true">
<intent-filter>
<action android:name="androidx.media3.session.MediaSessionService"/>
</intent-filter>
</service>
You must define a foregroundServiceType
that includes mediaPlayback
when your app is running on a device with Android
10 onwards.
Be sure to release the media session (and player) in your service’s onDestroy()
lifecycle callback:
override fun onDestroy() {
mediaSession?.run {
player.release()
release()
mediaSession = null
}
}
Control playback in the media session
In the Activity or Fragment containing your player UI, you can establish a link
between the UI and your media session using a MediaController
. Your UI uses
the media controller to send commands from your UI to the player within the
session.
Obtain a MediaController
from your MediaSession
by creating a SessionToken
in the onStart()
method of your Activity or Fragment.
override fun onStart() {
val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java)
}
Use this SessionToken
to build a MediaController
. Doing so connects the
controller to the given session. This takes place asynchronously so you
should listen for the result and assign it when constructed. This example shows
how you can do this to connect the MediaController
to your player UI.
val controllerFuture =
MediaController.Builder(this, sessionToken))
.buildAsync()
controllerFuture.addListener({
playerView.player = controllerFuture.get()
}, MoreExecutors.directExecutor())
Handle UI commands
The MediaSession
receives commands from the controller through its
SessionCallback
. Initializing a MediaSession
creates a default
implementation of SessionCallback
that automatically handles all commands
that your MediaController
sends to your player.
You should also release the controller in the onStop()
method of its hosting
Activity or Fragment by calling
MediaController.releaseFuture(controllerFuture)
.
Notification
A MediaSessionService
automatically creates a MediaNotification
for you
that should work in most cases. By default, the published notification is a
MediaStyle
notification that stays updated with the latest information
from your media session and displays playback controls. The MediaNotification
is aware of your session and can be used to control playback for any other apps
that are connected to the same session.
For example, a music streaming app using a MediaSessionService
would create a
MediaNotification
that displays the title, artist, and album art for the
current song playing alongside playback controls based on your MediaSession
configuration.
If you’d like to provide your own custom MediaNotification
, you can override
MediaSessionService.onUpdateNotification()
.