Save the date! Android Dev Summit is coming to Mountain View, CA on November 7-8, 2018.

belongs to Maven artifact androidx.media2:media2:1.0.0-alpha03

MediaSessionService2

public abstract class MediaSessionService2
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ androidx.media2.MediaSessionService2


Base class for media session services, which is the service version of the MediaSession2.

It's highly recommended for an app to use this instead of MediaSession2 if it wants to keep media playback in the background.

Here's the benefits of using MediaSessionService2 instead of MediaSession2.

  • Another app can know that your app supports MediaSession2 even when your app isn't running.
  • Another app can start playback of your app even when your app isn't running.
For example, user's voice command can start playback of your app even when it's not running.

To extend this class, adding followings directly to your AndroidManifest.xml.

 <service android:name="component_name_of_your_implementation" >
   <intent-filter>
     <action android:name="android.media.MediaSessionService2" />
   </intent-filter>
 </service>

A MediaSessionService2 is another form of MediaSession2. IDs shouldn't be shared between the MediaSessionService2 and MediaSession2. By default, an empty string will be used for ID of the service. If you want to specify an ID, declare metadata in the manifest as follows.

 <service android:name="component_name_of_your_implementation" >
   <intent-filter>
     <action android:name="android.media.MediaSessionService2" />
   </intent-filter>
   <meta-data android:name="android.media.session2.SESSION_ID"
       android:value="session_id"/>
 </service>

It's recommended for an app to have a single MediaSessionService2 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 this app.

If there's conflicts with the session ID among the services, services wouldn't be available for any controllers.

Topic covered here:

  1. Service Lifecycle
  2. Permissions

Service Lifecycle

Session service is bounded service. When a MediaController2 is created for the session service, the controller binds to the session service. onCreateSession(String) may be called after the onCreate() if the service hasn't created yet.

After the binding, session's MediaSession2.SessionCallback.onConnect(MediaSession2, 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() is called 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 the playback is stopped.

The service is destroyed when the session is closed, or no media controller is bounded to the session while the service is not running as a foreground service.

Permissions

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 MediaSession2.SessionCallback.onConnect(MediaSession2, ControllerInfo).

Summary

Nested classes

class MediaSessionService2.MediaNotification

Returned by MediaSessionService2.onUpdateNotification() for making session service foreground service to keep playback running in the background. 

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

String SERVICE_META_DATA_SESSION_ID

Name under which a MediaSessionService2 component publishes information about itself.

Inherited constants

Public constructors

MediaSessionService2()

Public methods

final MediaSession2 getSession()

Get instance of the MediaSession2 that you've previously created with the onCreateSession(String) for this service.

IBinder onBind(Intent intent)

Default implementation for MediaSessionService2 to handle incoming binding request.

void onCreate()

Default implementation for MediaSessionService2 to initialize session service.

abstract MediaSession2 onCreateSession(String sessionId)

Called when another app requested to start this service to get MediaSession2.

MediaSessionService2.MediaNotification onUpdateNotification()

Called when notification UI needs update.

Inherited methods

Constants

SERVICE_INTERFACE

public static final String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

Constant Value: "android.media.MediaSessionService2"

SERVICE_META_DATA_SESSION_ID

public static final String SERVICE_META_DATA_SESSION_ID

Name under which a MediaSessionService2 component publishes information about itself. This meta-data must provide a string value for the ID.

Constant Value: "android.media.session2.SESSION_ID"

Public constructors

MediaSessionService2

public MediaSessionService2 ()

Public methods

getSession

public final MediaSession2 getSession ()

Get instance of the MediaSession2 that you've previously created with the onCreateSession(String) for this service.

This may be null before the onCreate() is finished.

Returns
MediaSession2 created session

onBind

public IBinder onBind (Intent intent)

Default implementation for MediaSessionService2 to handle incoming binding request. If the request is for getting the session, the intent will have action SERVICE_INTERFACE.

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.

Returns
IBinder Binder

onCreate

public void onCreate ()

Default implementation for MediaSessionService2 to initialize session service.

Override this method if you need your own initialization. Derived classes MUST call through to the super class's implementation of this method.

onCreateSession

public abstract MediaSession2 onCreateSession (String sessionId)

Called when another app requested to start this service to get MediaSession2.

Session service will accept or reject the connection with the MediaSession2.SessionCallback in the created session.

Service wouldn't run if null is returned or session's ID doesn't match with the expected ID that you've specified through the AndroidManifest.xml.

This method will be called on the main thread.

Parameters
sessionId String: session id written in the AndroidManifest.xml.

Returns
MediaSession2 a new session

onUpdateNotification

public MediaSessionService2.MediaNotification onUpdateNotification ()

Called when notification UI needs update. Override this method to show or cancel your own notification UI.

This would be called when player state changed,

With the notification returned here, the service become foreground service when the playback is started. It becomes background service after the playback is stopped.

Returns
MediaSessionService2.MediaNotification a MediaSessionService2.MediaNotification. If it's null, notification wouldn't be shown.