MediaSessionService

public static final String SERVICE_INTERFACE = "androidx.media3.session.MediaSessionService"

The action for Intent filter that must be declared by the service.

public MediaSessionService()

Creates a service.

public final void addSession(MediaSession session)

Adds a MediaSession to this service. This is not necessary for most media apps. See Supporting Multiple Sessions for details.

The added session will be removed automatically when the session is released.

This method can be called from any thread.

@UnstableApi
public final void clearListener()

Clears the listener.

This method can be called from any thread.

public final List<MediaSession> getSessions()

Returns the list of sessions that you've added to this service via addSession or onGetSession.

This method can be called from any thread.

@UnstableApi
public boolean isPlaybackOngoing()

Returns whether there is a session with ongoing playback that must be paused or stopped before being able to terminate the service by calling stopSelf.

public final boolean isSessionAdded(MediaSession session)

Returns whether session has been added to this service via addSession or onGetSession.

This method can be called from any thread.

@CallSuper
public @Nullable IBinder onBind(@Nullable Intent intent)

Called when a component is about to bind to the service.

The default implementation handles the incoming requests from controllers. In this case, the intent will have the action SERVICE_INTERFACE. Override this method if this service also needs to handle actions other than SERVICE_INTERFACE.

This method will be called on the main thread.

@CallSuper
public void onCreate()

Called when the service is created.

Override this method if you need your own initialization.

This method will be called on the main thread.

@CallSuper
public void onDestroy()

Called when the service is no longer used and is being removed.

Override this method if you need your own clean up.

This method will be called on the main thread.

public abstract @Nullable MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo)

Called when a MediaController is created with this service's SessionToken. Return a MediaSession that the controller will connect to, or null to reject the connection request.

The service automatically maintains the returned sessions. In other words, a session returned by this method will be added to the service, and removed from the service when the session is closed. You don't need to manually call addSession nor removeSession.

There are two special cases where the getPackageName returns a non-existent package name:

• When the service is started by a media button event, the package name will be ACTION_MEDIA_BUTTON. If you want to allow the service to be started by media button events, do not return null.
• When a legacy android.media.browse.MediaBrowser or a android.support.v4.media.MediaBrowserCompat tries to connect, the package name will be SERVICE_INTERFACE. If you want to allow the service to be bound by the legacy media browsers, do not return null.

For those special cases, the values returned by getUid and getConnectionHints have no meaning.

This method will be called on the main thread.

@CallSuper
public int onStartCommand(@Nullable Intent intent, int flags, int startId)

Called when a component calls startService.

The default implementation handles the incoming media button events. In this case, the intent will have the action ACTION_MEDIA_BUTTON. Override this method if this service also needs to handle actions other than ACTION_MEDIA_BUTTON.

This method will be called on the main thread.

public void onTaskRemoved(@Nullable Intent rootIntent)

If playback is ongoing, the service continues running in the foreground when the app is dismissed from the recent apps. Otherwise, the service is stopped by calling stopSelf which terminates the service lifecycle and triggers onDestroy that an app can override to release the sessions and other resources.

An app can safely override this method without calling super to implement a different behaviour, for instance unconditionally calling pauseAllPlayersAndStopSelf to stop the service even when playing. However, if playback is not ongoing, the service must be terminated otherwise the service will be crashed and restarted by the system.

Note: The service can't be stopped until all media controllers have been unbound. Hence, an app needs to release all internal controllers that have connected to the service (for instance from an activity in onStop). If an app allows external apps to connect a MediaController to the service, these controllers also need to be disconnected. In such a scenario of external bound clients, an app needs to override this method to release the session before calling stopSelf.

public void onUpdateNotification(
    MediaSession session,
    boolean startInForegroundRequired
)

Called when a notification needs to be updated. Override this method to show or cancel your own notifications.

This method is called whenever the service has detected a change that requires to show, update or cancel a notification with a flag startInForegroundRequired suggested by the service whether starting in the foreground is required. The method will be called on the application thread of the app that the service belongs to.

Override this method to create your own notification and customize the foreground handling of your service.

The default implementation will present a default notification or the notification provided by the MediaNotification.Provider that is set by the app. Further, the service is started in the foreground when playback is ongoing and put back into background otherwise.

Apps targeting SDK_INT >= 28 must request the permission, FOREGROUND_SERVICE.

This method will be called on the main thread.

@UnstableApi
public void pauseAllPlayersAndStopSelf()

Pauses the player of each session managed by the service and calls stopSelf.

This terminates the service lifecycle and triggers onDestroy that an app can override to release the sessions and other resources.

public final void removeSession(MediaSession session)

Removes a MediaSession from this service. This is not necessary for most media apps. See Supporting Multiple Sessions for details.

This method can be called from any thread.

@UnstableApi
public final void setListener(MediaSessionService.Listener listener)

Sets the listener.

This method can be called from any thread.

@UnstableApi
protected final void setMediaNotificationProvider(
    MediaNotification.Provider mediaNotificationProvider
)

Sets the MediaNotification.Provider to customize notifications.

This should be called before onCreate returns.

This method can be called from any thread.