MediaSessionService

abstract class MediaSessionService : Service

kotlin.Any
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ androidx.media3.session.MediaSessionService
Known direct subclasses
MediaLibraryService

Superclass to be extended by services hosting media library sessions.

Superclass to be extended by services hosting media sessions.

It's highly recommended for an app to use this class if media playback should continue while in the background. The service allows other apps to know that your app supports even when your app isn't running. This way, a user voice command may be able start your app to play media.

To extend this class, declare the intent filter in your AndroidManifest.xml: 

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

You may also declare the action android.media.browse.MediaBrowserService for compatibility with android.support.v4.media.MediaBrowserCompat. This service can handle the case automatically.

It's recommended for an app to have a single service declared in the manifest. Otherwise, your app might be shown twice in the list of the controller apps, or another app might fail to pick the right service when it wants to start a playback on this app. If you want to provide multiple sessions, take a look at Supporting Multiple Sessions.

Topics covered here:

  1. Service Lifecycle
  2. Supporting Multiple Sessions

Service Lifecycle

A media session service is a bound service and its foreground service type must include mediaPlayback. When a MediaController is created for the service, the controller binds to the service. onGetSession will be called from onBind.

After binding, the session's onConnect will be called to accept or reject the connection request from the controller. If it's accepted, the controller will be available and keep the binding. If it's rejected, the controller will unbind.

onUpdateNotification will be called whenever a notification needs to be shown, updated or cancelled. The default implementation will display notifications using a default UI or using a MediaNotification.Provider that's set with setMediaNotificationProvider. In addition, when playback starts, the service will become a foreground service. It's required to keep the playback after the controller is destroyed. The service will become a background service when all playbacks are stopped. Apps targeting SDK_INT >= 28 must request the permission, FOREGROUND_SERVICE, in order to make the service foreground. You can control when to show or hide notifications by overriding onUpdateNotification. In this case, you must also start or stop the service from the foreground, when playback starts or stops respectively.

The service will be destroyed when all sessions are released, or no controller is binding to the service while the service is in the background.

Supporting Multiple Sessions

Generally, multiple sessions aren't necessary for most media apps. One exception is if your app can play multiple media contents at the same time, but only for playback of video-only media or remote playback, since the audio focus policy recommends not playing multiple audio contents at the same time. Also, keep in mind that multiple media sessions would make Android Auto and Bluetooth devices with a display to show your apps multiple times, because they list up media sessions, not media apps.

However, if you're capable of handling multiple playbacks and want to keep their sessions while the app is in the background, create multiple sessions and add them to this service with addSession.

Note that a MediaController can be created with SessionToken to connect to a session in this service. In that case, onGetSession will be called to decide which session to handle the connection request. Pick the best session among the added sessions, or create a new session and return it from onGetSession.

Summary

Nested types

Listener for MediaSessionService.

Constants
const String!
SERVICE_INTERFACE = "androidx.media3.session.MediaSessionService"

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

Public constructors

Creates a service.

Public functions
Unit

Adds a MediaSession to this service.
Unit

Clears the listener.
(Mutable)List<MediaSession!>!

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

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.
Boolean

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

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

Called when the service is created.
Unit

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

Called when a MediaController is created with this service's SessionToken.
Int
@CallSuper
onStartCommand(intent: Intent?, flags: Int, startId: Int)

Called when a component calls startService.
Unit
onTaskRemoved(rootIntent: Intent?)

If playback is ongoing, the service continues running in the foreground when the app is dismissed from the recent apps.
Unit

This function is deprecated.

Use onUpdateNotification instead.
Unit
onUpdateNotification(
    session: MediaSession!,
    startInForegroundRequired: Boolean
)

Called when a notification needs to be updated.
Unit

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

Removes a MediaSession from this service.
Unit

Sets the listener.

Protected functions
Unit

Sets the MediaNotification.Provider to customize notifications.

Inherited Constants
From android.content.ComponentCallbacks2
const Int
const Int
const Int
const Int
const Int
const Int
const Int
From android.content.Context
const String!
ACCESSIBILITY_SERVICE = "accessibility"
const String!
ACCOUNT_SERVICE = "account"
const String!
ACTIVITY_SERVICE = "activity"
const String!
ALARM_SERVICE = "alarm"
const String!
APPWIDGET_SERVICE = "appwidget"
const String!
APP_OPS_SERVICE = "appops"
const String!
APP_SEARCH_SERVICE = "app_search"
const String!
AUDIO_SERVICE = "audio"
const String!
BATTERY_SERVICE = "batterymanager"
const Int
const Int
const Int
const Int
const Int
const Int
const Int
BIND_EXTERNAL_SERVICE = -2147483648
const Long
BIND_EXTERNAL_SERVICE_LONG = 4611686018427387904
const Int
const Int
const Int
const Int
const Int
const Int
const String!
BIOMETRIC_SERVICE = "biometric"
const String!
BLOB_STORE_SERVICE = "blob_store"
const String!
BLUETOOTH_SERVICE = "bluetooth"
const String!
BUGREPORT_SERVICE = "bugreport"
const String!
CAMERA_SERVICE = "camera"
const String!
CAPTIONING_SERVICE = "captioning"
const String!
CARRIER_CONFIG_SERVICE = "carrier_config"
const String!
CLIPBOARD_SERVICE = "clipboard"
const String!
COMPANION_DEVICE_SERVICE = "companiondevice"
const String!
CONNECTIVITY_DIAGNOSTICS_SERVICE = "connectivity_diagnostics"
const String!
CONNECTIVITY_SERVICE = "connectivity"
const String!
CONSUMER_IR_SERVICE = "consumer_ir"
const Int
const Int
const Int
const String!
CREDENTIAL_SERVICE = "credential"
const String!
CROSS_PROFILE_APPS_SERVICE = "crossprofileapps"
const Int
const Int
const String!
DEVICE_LOCK_SERVICE = "device_lock"
const String!
DEVICE_POLICY_SERVICE = "device_policy"
const String!
DISPLAY_HASH_SERVICE = "display_hash"
const String!
DISPLAY_SERVICE = "display"
const String!
DOMAIN_VERIFICATION_SERVICE = "domain_verification"
const String!
DOWNLOAD_SERVICE = "download"
const String!
DROPBOX_SERVICE = "dropbox"
const String!
EUICC_SERVICE = "euicc"
const String!
FILE_INTEGRITY_SERVICE = "file_integrity"
const String!
FINGERPRINT_SERVICE = "fingerprint"
const String!
GAME_SERVICE = "game"
const String!
GRAMMATICAL_INFLECTION_SERVICE = "grammatical_inflection"
const String!
HARDWARE_PROPERTIES_SERVICE = "hardware_properties"
const String!
HEALTHCONNECT_SERVICE = "healthconnect"
const String!
INPUT_METHOD_SERVICE = "input_method"
const String!
INPUT_SERVICE = "input"
const String!
IPSEC_SERVICE = "ipsec"
const String!
JOB_SCHEDULER_SERVICE = "jobscheduler"
const String!
KEYGUARD_SERVICE = "keyguard"
const String!
LAUNCHER_APPS_SERVICE = "launcherapps"
const String!
LAYOUT_INFLATER_SERVICE = "layout_inflater"
const String!
LOCALE_SERVICE = "locale"
const String!
LOCATION_SERVICE = "location"
const String!
MEDIA_COMMUNICATION_SERVICE = "media_communication"
const String!
MEDIA_METRICS_SERVICE = "media_metrics"
const String!
MEDIA_PROJECTION_SERVICE = "media_projection"
const String!
MEDIA_ROUTER_SERVICE = "media_router"
const String!
MEDIA_SESSION_SERVICE = "media_session"
const String!
MIDI_SERVICE = "midi"
const Int
MODE_APPEND = 32768
const Int
const Int

This property is deprecated.
const Int
const Int
const Int

This property is deprecated.
const Int

This property is deprecated.
const String!
const String!
NFC_SERVICE = "nfc"
const String!
NOTIFICATION_SERVICE = "notification"
const String!
NSD_SERVICE = "servicediscovery"
const String!
OVERLAY_SERVICE = "overlay"
const String!
PEOPLE_SERVICE = "people"
const String!
PERFORMANCE_HINT_SERVICE = "performance_hint"
const String!
POWER_SERVICE = "power"
const String!
PRINT_SERVICE = "print"
const Int
const Int
const Int
const String!
RESTRICTIONS_SERVICE = "restrictions"
const String!
ROLE_SERVICE = "role"
const String!
SEARCH_SERVICE = "search"
const String!
SENSOR_SERVICE = "sensor"
const String!
SHORTCUT_SERVICE = "shortcut"
const String!
STATUS_BAR_SERVICE = "statusbar"
const String!
STORAGE_SERVICE = "storage"
const String!
STORAGE_STATS_SERVICE = "storagestats"
const String!
SYSTEM_HEALTH_SERVICE = "systemhealth"
const String!
TELECOM_SERVICE = "telecom"
const String!
TELEPHONY_IMS_SERVICE = "telephony_ims"
const String!
const String!
TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"
const String!
TEXT_CLASSIFICATION_SERVICE = "textclassification"
const String!
const String!
TV_INPUT_SERVICE = "tv_input"
const String!
TV_INTERACTIVE_APP_SERVICE = "tv_interactive_app"
const String!
UI_MODE_SERVICE = "uimode"
const String!
USAGE_STATS_SERVICE = "usagestats"
const String!
USB_SERVICE = "usb"
const String!
USER_SERVICE = "user"
const String!
VIBRATOR_MANAGER_SERVICE = "vibrator_manager"
const String!
VIBRATOR_SERVICE = "vibrator"

This property is deprecated.
const String!
VIRTUAL_DEVICE_SERVICE = "virtualdevice"
const String!
VPN_MANAGEMENT_SERVICE = "vpn_management"
const String!
WALLPAPER_SERVICE = "wallpaper"
const String!
WIFI_AWARE_SERVICE = "wifiaware"
const String!
WIFI_P2P_SERVICE = "wifip2p"
const String!
const String!
WIFI_SERVICE = "wifi"
const String!
WINDOW_SERVICE = "window"
From android.app.Service
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int
const Int

This property is deprecated.
const Int

Inherited functions
From android.content.Context
Int
ColorStateList!
Drawable!
String!
getString(resId: Int)
T!
<T> getSystemService(serviceClass: Class<T!>!)
CharSequence!
getText(resId: Int)
TypedArray!
Unit
Unit
sendBroadcastWithMultiplePermissions(
    intent: Intent!,
    receiverPermissions: Array<String!>!
)
From android.content.ContextWrapper
Boolean
bindIsolatedService(
    service: Intent!,
    flags: Int,
    instanceName: String!,
    executor: Executor!,
    conn: ServiceConnection!
)
Boolean
bindService(service: Intent!, conn: ServiceConnection!, flags: Int)
Boolean
bindServiceAsUser(
    service: Intent!,
    conn: ServiceConnection!,
    flags: Int,
    user: UserHandle!
)
Int
Int
IntArray<Int>!
checkCallingOrSelfUriPermissions(
    uris: (Mutable)List<Uri!>!,
    modeFlags: Int
)
Int
Int
checkCallingUriPermission(uri: Uri!, modeFlags: Int)
IntArray<Int>!
checkCallingUriPermissions(uris: (Mutable)List<Uri!>!, modeFlags: Int)
Int
checkPermission(permission: String!, pid: Int, uid: Int)
Int
Int
checkUriPermission(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)
IntArray<Int>!
checkUriPermissions(
    uris: (Mutable)List<Uri!>!,
    pid: Int,
    uid: Int,
    modeFlags: Int
)
Unit

This function is deprecated.
Context!
createAttributionContext(attributionTag: String!)
Context!
createConfigurationContext(overrideConfiguration: Configuration!)
Context!
createContext(contextParams: ContextParams!)
Context!
Context!
Context!
Context!
Context!
createPackageContext(packageName: String!, flags: Int)
Context!
createWindowContext(type: Int, options: Bundle!)
Array<String!>!
Boolean
Boolean
Boolean
Unit
enforceCallingOrSelfPermission(permission: String!, message: String!)
Unit
enforceCallingOrSelfUriPermission(
    uri: Uri!,
    modeFlags: Int,
    message: String!
)
Unit
enforceCallingPermission(permission: String!, message: String!)
Unit
enforceCallingUriPermission(uri: Uri!, modeFlags: Int, message: String!)
Unit
enforcePermission(permission: String!, pid: Int, uid: Int, message: String!)
Unit
enforceUriPermission(
    uri: Uri!,
    pid: Int,
    uid: Int,
    modeFlags: Int,
    message: String!
)
Array<String!>!
Context!
ApplicationInfo!
AssetManager!
AttributionSource!
String!
Context!
File!
ClassLoader!
File!
ContentResolver!
File!
File!
Int
File!
getDir(name: String!, mode: Int)
Display!
File!
Array<File!>!
File!
Array<File!>!
Array<File!>!

This function is deprecated.
File!
File!
Executor!
Looper!
File!
File!
Array<File!>!
String!
String!
PackageManager!
String!
String!
ContextParams!
Resources!
SharedPreferences!
getSharedPreferences(name: String!, mode: Int)
Any!
String!
getSystemServiceName(serviceClass: Class<Any!>!)
Resources.Theme!
Drawable!

This function is deprecated.
Int

This function is deprecated.
Int

This function is deprecated.
Unit
grantUriPermission(toPackage: String!, uri: Uri!, modeFlags: Int)
Boolean
Boolean
Boolean
Boolean
moveDatabaseFrom(sourceContext: Context!, name: String!)
Boolean
moveSharedPreferencesFrom(sourceContext: Context!, name: String!)
FileInputStream!
FileOutputStream!
openFileOutput(name: String!, mode: Int)
SQLiteDatabase!
openOrCreateDatabase(
    name: String!,
    mode: Int,
    factory: SQLiteDatabase.CursorFactory!
)
Drawable!

This function is deprecated.
Unit
Unit
Intent!
Unit

This function is deprecated.
Unit

This function is deprecated.
Unit
Unit
revokeUriPermission(uri: Uri!, modeFlags: Int)
Unit
Unit
Unit
sendOrderedBroadcast(intent: Intent!, receiverPermission: String!)
Unit
sendOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    receiverPermission: String!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)
Unit

This function is deprecated.
Unit

This function is deprecated.
Unit
sendStickyOrderedBroadcast(
    intent: Intent!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.
Unit
sendStickyOrderedBroadcastAsUser(
    intent: Intent!,
    user: UserHandle!,
    resultReceiver: BroadcastReceiver!,
    scheduler: Handler!,
    initialCode: Int,
    initialData: String!,
    initialExtras: Bundle!
)

This function is deprecated.
Unit
setTheme(resid: Int)
Unit
setWallpaper(bitmap: Bitmap!)

This function is deprecated.
Unit
Unit
ComponentName!
Boolean
startInstrumentation(
    className: ComponentName!,
    profileFile: String!,
    arguments: Bundle!
)
Unit
startIntentSender(
    intent: IntentSender!,
    fillInIntent: Intent!,
    flagsMask: Int,
    flagsValues: Int,
    extraFlags: Int
)
ComponentName!
startService(service: Intent!)
Boolean
Unit
Unit
Unit
Unit
Unit
updateServiceGroup(conn: ServiceConnection!, group: Int, importance: Int)
From android.app.Service
Unit
Unit
dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)
Application!
Int
Unit
Unit
Unit
onRebind(intent: Intent!)
Unit
onStart(intent: Intent!, startId: Int)

This function is deprecated.
Unit
onTimeout(startId: Int)
Unit
onTrimMemory(level: Int)
Boolean
onUnbind(intent: Intent!)
Unit
startForeground(id: Int, notification: Notification!)
Unit
stopForeground(removeNotification: Boolean)

This function is deprecated.
Unit
Boolean
stopSelfResult(startId: Int)

Constants

SERVICE_INTERFACE

const val SERVICE_INTERFACE = "androidx.media3.session.MediaSessionService": String!

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

Public constructors

MediaSessionService

MediaSessionService()

Creates a service.

Public functions

addSession

fun addSession(session: MediaSession!): Unit

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.

Parameters
session: MediaSession!

A session to be added.
See also
removeSession
getSessions

clearListener

@UnstableApi
fun clearListener(): Unit

Clears the listener.

This method can be called from any thread.

getSessions

fun getSessions(): (Mutable)List<MediaSession!>!

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

This method can be called from any thread.

isPlaybackOngoing

@UnstableApi
fun isPlaybackOngoing(): Boolean

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.

isSessionAdded

fun isSessionAdded(session: MediaSession!): Boolean

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

This method can be called from any thread.

onBind

@CallSuper
fun onBind(intent: Intent?): IBinder?

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.

onCreate

@CallSuper
fun onCreate(): Unit

Called when the service is created.

Override this method if you need your own initialization.

This method will be called on the main thread.

onDestroy

@CallSuper
fun onDestroy(): Unit

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.

onGetSession

abstract fun onGetSession(controllerInfo: MediaSession.ControllerInfo!): MediaSession?

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.

Parameters
controllerInfo: MediaSession.ControllerInfo!

The information of the controller that is trying to connect.
Returns
MediaSession?

A MediaSession for the controller, or null to reject the connection.
See also
MediaSession.Builder
getSessions

onStartCommand

@CallSuper
fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int

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.

onTaskRemoved

fun onTaskRemoved(rootIntent: Intent?): Unit

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.

onUpdateNotification

fun onUpdateNotification(session: MediaSession!): Unit

onUpdateNotification

fun onUpdateNotification(
    session: MediaSession!,
    startInForegroundRequired: Boolean
): Unit

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.

Parameters
session: MediaSession!

A session that needs notification update.
startInForegroundRequired: Boolean

Whether the service is required to start in the foreground.

pauseAllPlayersAndStopSelf

@UnstableApi
fun pauseAllPlayersAndStopSelf(): Unit

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.

removeSession

fun removeSession(session: MediaSession!): Unit

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.

Parameters
session: MediaSession!

A session to be removed.
See also
addSession
getSessions

setListener

@UnstableApi
fun setListener(listener: MediaSessionService.Listener!): Unit

Sets the listener.

This method can be called from any thread.

Protected functions

setMediaNotificationProvider

@UnstableApi
protected fun setMediaNotificationProvider(
    mediaNotificationProvider: MediaNotification.Provider!
): Unit

Sets the MediaNotification.Provider to customize notifications.

This should be called before onCreate returns.

This method can be called from any thread.