abstract class MediaSessionService : Service
Base class for media session services, which is the service containing
It's highly recommended for an app to use this if it wants to keep media playback in the background.
Here are the benefits of using
- Another app can know that your app supports
MediaSessioneven when your app isn't running.
- Another app can start playback of your app even when your app isn't running.
To extend this class, adding followings directly to your
<service android:name="component_name_of_your_implementation" > <intent-filter> <action android:name="androidx.media2.session.MediaSessionService" /> </intent-filter> </service>
You may also declare
android.media.browse.MediaBrowserServicefor compatibility with
android.support.v4.media.MediaBrowserCompat. This service can handle it automatically.
It's recommended for an app to have a single
MediaSessionService declared in the manifest. Otherwise, your app might be shown twice in the list of the Auto/Wearable, or another app fails to pick the right session service when it wants to start the playback of this app. If you want to provide multiple sessions here, take a look at Supporting Multiple Sessions.
Topics covered here:
Session service is a bound service. When a
MediaController is created for the session service, the controller binds to the session service.
onGetSession(ControllerInfo) would be called inside of the
After the binding, session's
MediaSession.SessionCallback#onConnect(MediaSession, MediaSession.ControllerInfo) will be called to accept or reject connection request from a controller. If the connection is rejected, the controller will unbind. If it's accepted, the controller will be available to use and keep binding.
When playback is started for this session service,
onUpdateNotification(MediaSession) is called for the playback's session and service would become a foreground service. It's needed to keep playback after the controller is destroyed. The session service becomes background service when all playbacks are stopped. Apps targeting API
android.os.Build.VERSION_CODES#P or later must request the permission
android.Manifest.permission#FOREGROUND_SERVICE in order to make the service foreground.
The service is destroyed when the all sessions are closed, or no media controller is binding to the session while the service is not running as a foreground service.
Any app can bind to the session service with controller, but the controller can be used only if the session service accepted the connection request through
Supporting Multiple SessionsGenerally speaking, multiple sessions aren't necessary for most media apps. One exception is if your app can play multiple media content at the same time, but only for the playback of video-only media or remote playback, since audio focus policy recommends not playing multiple audio content at the same time. Also keep in mind that multiple media sessions would make Android Auto and Bluetooth device with display to show your apps multiple times, because they list up media sessions, not media apps.
However, if you're capable of handling multiple playback and want to keep their sessions while the app is in the background, create multiple sessions and add to this service with
MediaController can be created with
SessionToken for connecting any session in this service. In that case,
onGetSession(ControllerInfo) will be called to know which session to handle incoming connection request. Pick the best session among added sessions, or create new one and return from the
Adds a session to this service.
Default implementation for
Called by the system when the service is first created.
Called by the system to notify that it is no longer used and is being removed.
Called when notification UI needs update.
Removes a session from this service.
static val SERVICE_INTERFACE: String
Intent that must be declared as handled by the service.
fun addSession(@NonNull session: MediaSession): Unit
Adds a session to this service. This is not necessary for most media apps. See Supporting Multiple Sessions for detail.
Added session will be removed automatically when it's closed, or removed when
removeSession is called.
||MediaSession: a session to be added.|
@NonNull fun getSessions(): MutableList<MediaSession!>
Override this method if this service also needs to handle binder requests other than
SERVICE_INTERFACE. Derived classes MUST call through to the super class's implementation of this method.
@CallSuper open fun onCreate(): Unit
Called by the system when the service is first created. Do not call this method directly.
Override this method if you need your own initialization. Derived classes MUST call through to the super class's implementation of this method.
@CallSuper open fun onDestroy(): Unit
Called by the system to notify that it is no longer used and is being removed. Do not call this method directly.
Override this method if you need your own clean up. Derived classes MUST call through to the super class's implementation of this method.
@Nullable abstract fun onGetSession(@NonNull controllerInfo: MediaSession.ControllerInfo): MediaSession?
Called when a
MediaController is created with the this service's
SessionToken. Return the session for telling the controller which session to connect. Return
null to reject the connection from this controller.
Session service automatically maintains the returned session. In other words, session returned here will be added here and removed when the session is closed. You don't need to manually call
There are two special cases where the
ControllerInfo#getPackageName() returns non-existent package name:
- When the service is being started through the media button intent, the method will return
Intent#ACTION_MEDIA_BUTTON. If you want to allow the service being started by the media button events, do not return
- When the legacy
android.support.v4.media.MediaBrowserCompattries to connect, the method will return
MediaBrowserServiceCompat#SERVICE_INTERFACE. If you want to allow the service being bound by the legacy media browsers, do not return
ControllerInfo#getConnectionHints()have no meaning.
This method is always called on the main thread.
||MediaSession.ControllerInfo: information of the controller which is trying to connect|
@Nullable open fun onUpdateNotification(@NonNull session: MediaSession): MediaSessionService.MediaNotification?
Called when notification UI needs update. Override this method to show or cancel your own notification UI.
This would be called on
MediaSession's callback executor when player state is changed, or when the current media item of the session is changed.
With the notification returned here, the service becomes foreground service when the playback is started. Apps targeting API
android.os.Build.VERSION_CODES#P or later must request the permission
android.Manifest.permission#FOREGROUND_SERVICE in order to use this API. It becomes background service after the playback is stopped.
||MediaSession: a session that needs notification update|