MediaSessionService

Artifact: androidx.media3:media3-session

Kotlin |Java

abstract class MediaSessionService : Service

kotlin.Any
↳	android.content.Context
	↳	android.content.ContextWrapper
		↳	android.app.Service
			↳	androidx.media3.session.MediaSessionService

Known direct subclasses

MediaLibraryService

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 MediaSession 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:

Service Lifecycle
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
`@UnstableApi interface MediaSessionService.Listener` Listener for `MediaSessionService`.
`@UnstableApi @Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @IntDef(value = ) annotation MediaSessionService.ShowNotificationForIdlePlayerMode` The behavior for showing notifications when the `Player` is in `STATE_IDLE`.

Constants
`const Long`	`@UnstableApi DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS = 600000` The default timeout for a session to stay in a foreground service state after it paused, stopped, failed or ended.
`const String!`	`SERVICE_INTERFACE = "androidx.media3.session.MediaSessionService"` The action for `Intent` filter that must be declared by the service.
`const Int`	`@UnstableApi SHOW_NOTIFICATION_FOR_IDLE_PLAYER_AFTER_STOP_OR_ERROR = 3` Shows a notification when the `Player` is in `STATE_IDLE` due to `stop` or an error, has media, and the notification wasn't explicitly dismissed.
`const Int`	`@UnstableApi SHOW_NOTIFICATION_FOR_IDLE_PLAYER_ALWAYS = 1` Always show a notification when the `Player` is in `STATE_IDLE`, has media, and the notification wasn't explicitly dismissed.
`const Int`	`@UnstableApi SHOW_NOTIFICATION_FOR_IDLE_PLAYER_NEVER = 2` Never show a notification when the `Player` is in `STATE_IDLE`.

Public constructors
`MediaSessionService()` Creates a service.

Public functions
`Unit`	`addSession(session: MediaSession!)` Adds a `MediaSession` to this service.
`Unit`	`@UnstableApi clearListener()` Clears the `listener`.
`(Mutable)List<MediaSession!>!`	`getSessions()` Returns the list of `sessions` that you've added to this service via `addSession` or `onGetSession`.
`Boolean`	`@UnstableApi isPlaybackOngoing()` Returns whether there is a session with ongoing user-engaged playback that is run in a foreground service.
`Boolean`	`isSessionAdded(session: MediaSession!)` Returns whether `session` has been added to this service via `addSession` or `onGetSession`.
`IBinder?`	`@CallSuper onBind(intent: Intent?)` Called when a component is about to bind to the service.
`Unit`	`@CallSuper onCreate()` Called when the service is created.
`Unit`	`@CallSuper onDestroy()` Called when the service is no longer used and is being removed.
`abstract MediaSession?`	`onGetSession(controllerInfo: MediaSession.ControllerInfo!)` 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?)` This method can be overridden to customize the behavior of when the app is dismissed from the recent apps.
`Unit`	`onUpdateNotification(session: MediaSession!)` This function is deprecated. Use `onUpdateNotification` instead.
`Unit`	`onUpdateNotification( session: MediaSession!, startInForegroundRequired: Boolean )` Called when a notification needs to be updated.
`Unit`	`@UnstableApi pauseAllPlayersAndStopSelf()` Pauses the player of each session managed by the service, ensures the foreground service is stopped, and calls `stopSelf`.
`Unit`	`removeSession(session: MediaSession!)` Removes a `MediaSession` from this service.
`Unit`	`@UnstableApi setForegroundServiceTimeoutMs(foregroundServiceTimeoutMs: Long)` Sets the timeout for a session to stay in a foreground service state after it paused, stopped, failed or ended.
`Unit`	`@UnstableApi setListener(listener: MediaSessionService.Listener!)` Sets the `listener`.
`Unit`	`@UnstableApi setShowNotificationForIdlePlayer( @MediaSessionService.ShowNotificationForIdlePlayerMode showNotificationForIdlePlayerMode: Int )` Sets whether and when a notification for a `Player` in `STATE_IDLE` should be shown.
`Unit`	`@UnstableApi triggerNotificationUpdate()` Manually trigger a notification update.

Protected functions
`Unit`	`@UnstableApi setMediaNotificationProvider( mediaNotificationProvider: MediaNotification.Provider! )` Sets the `MediaNotification.Provider` to customize notifications.

Inherited Constants

From android.content.ComponentCallbacks2

`const Int`	`TRIM_MEMORY_BACKGROUND = 40`
`const Int`	`TRIM_MEMORY_COMPLETE = 80` This property is deprecated.
`const Int`	`TRIM_MEMORY_MODERATE = 60` This property is deprecated.
`const Int`	`TRIM_MEMORY_RUNNING_CRITICAL = 15` This property is deprecated.
`const Int`	`TRIM_MEMORY_RUNNING_LOW = 10` This property is deprecated.
`const Int`	`TRIM_MEMORY_RUNNING_MODERATE = 5` This property is deprecated.
`const Int`	`TRIM_MEMORY_UI_HIDDEN = 20`

From android.content.Context

`const String!`	`ACCESSIBILITY_SERVICE = "accessibility"`
`const String!`	`ACCOUNT_SERVICE = "account"`
`const String!`	`ACTIVITY_SERVICE = "activity"`
`const String!`	`ADVANCED_PROTECTION_SERVICE = "advanced_protection"`
`const String!`	`ALARM_SERVICE = "alarm"`
`const String!`	`APPWIDGET_SERVICE = "appwidget"`
`const String!`	`APP_FUNCTION_SERVICE = "app_function"`
`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`	`BIND_ABOVE_CLIENT = 8`
`const Int`	`BIND_ADJUST_WITH_ACTIVITY = 128`
`const Int`	`BIND_ALLOW_ACTIVITY_STARTS = 512`
`const Int`	`BIND_ALLOW_OOM_MANAGEMENT = 16`
`const Int`	`BIND_AUTO_CREATE = 1`
`const Int`	`BIND_DEBUG_UNBIND = 2`
`const Int`	`BIND_EXTERNAL_SERVICE = -2147483648`
`const Long`	`BIND_EXTERNAL_SERVICE_LONG = 4611686018427387904`
`const Int`	`BIND_IMPORTANT = 64`
`const Int`	`BIND_INCLUDE_CAPABILITIES = 4096`
`const Int`	`BIND_NOT_FOREGROUND = 4`
`const Int`	`BIND_NOT_PERCEPTIBLE = 256`
`const Int`	`BIND_PACKAGE_ISOLATED_PROCESS = 16384`
`const Int`	`BIND_SHARED_ISOLATED_PROCESS = 8192`
`const Int`	`BIND_WAIVE_PRIORITY = 32`
`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 String!`	`CONTACT_KEYS_SERVICE = "contact_keys"`
`const Int`	`CONTEXT_IGNORE_SECURITY = 2`
`const Int`	`CONTEXT_INCLUDE_CODE = 1`
`const Int`	`CONTEXT_RESTRICTED = 4`
`const String!`	`CREDENTIAL_SERVICE = "credential"`
`const String!`	`CROSS_PROFILE_APPS_SERVICE = "crossprofileapps"`
`const Int`	`DEVICE_ID_DEFAULT = 0`
`const Int`	`DEVICE_ID_INVALID = -1`
`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!`	`KEYSTORE_SERVICE = "keystore"`
`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_QUALITY_SERVICE = "media_quality"`
`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`	`MODE_ENABLE_WRITE_AHEAD_LOGGING = 8`
`const Int`	`MODE_MULTI_PROCESS = 4` This property is deprecated.
`const Int`	`MODE_NO_LOCALIZED_COLLATORS = 16`
`const Int`	`MODE_PRIVATE = 0`
`const Int`	`MODE_WORLD_READABLE = 1` This property is deprecated.
`const Int`	`MODE_WORLD_WRITEABLE = 2` This property is deprecated.
`const String!`	`NETWORK_STATS_SERVICE = "netstats"`
`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!`	`PERSISTENT_DATA_BLOCK_SERVICE = "persistent_data_block"`
`const String!`	`POWER_SERVICE = "power"`
`const String!`	`PRINT_SERVICE = "print"`
`const String!`	`PROFILING_SERVICE = "profiling"`
`const Int`	`RECEIVER_EXPORTED = 2`
`const Int`	`RECEIVER_NOT_EXPORTED = 4`
`const Int`	`RECEIVER_VISIBLE_TO_INSTANT_APPS = 1`
`const String!`	`RESTRICTIONS_SERVICE = "restrictions"`
`const String!`	`ROLE_SERVICE = "role"`
`const String!`	`SATELLITE_SERVICE = "satellite"`
`const String!`	`SEARCH_SERVICE = "search"`
`const String!`	`SECURITY_STATE_SERVICE = "security_state"`
`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!`	`TELEPHONY_SERVICE = "phone"`
`const String!`	`TELEPHONY_SUBSCRIPTION_SERVICE = "telephony_subscription_service"`
`const String!`	`TETHERING_SERVICE = "tethering"`
`const String!`	`TEXT_CLASSIFICATION_SERVICE = "textclassification"`
`const String!`	`TEXT_SERVICES_MANAGER_SERVICE = "textservices"`
`const String!`	`TV_AD_SERVICE = "tv_ad"`
`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!`	`WIFI_RTT_RANGING_SERVICE = "wifirtt"`
`const String!`	`WIFI_SERVICE = "wifi"`
`const String!`	`WINDOW_SERVICE = "window"`

From android.app.Service

`const Int`	`START_CONTINUATION_MASK = 15`
`const Int`	`START_FLAG_REDELIVERY = 1`
`const Int`	`START_FLAG_RETRY = 2`
`const Int`	`START_NOT_STICKY = 2`
`const Int`	`START_REDELIVER_INTENT = 3`
`const Int`	`START_STICKY = 1`
`const Int`	`START_STICKY_COMPATIBILITY = 0`
`const Int`	`STOP_FOREGROUND_DETACH = 2`
`const Int`	`STOP_FOREGROUND_LEGACY = 0` This property is deprecated.
`const Int`	`STOP_FOREGROUND_REMOVE = 1`

Inherited functions

From android.content.Context

`Int`	`getColor(id: Int)`
`ColorStateList!`	`getColorStateList(id: Int)`
`Drawable!`	`getDrawable(id: Int)`
`String!`	`getString(resId: Int)`
`T!`	`<T> getSystemService(serviceClass: Class<T!>!)`
`CharSequence!`	`getText(resId: Int)`
`TypedArray!`	`obtainStyledAttributes(set: AttributeSet!, attrs: IntArray!)`
`Unit`	`revokeSelfPermissionOnKill(permName: String!)`
`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!, flags: Context.BindServiceFlags!, executor: Executor!, conn: ServiceConnection! )`
`Boolean`	`bindServiceAsUser( service: Intent!, conn: ServiceConnection!, flags: Context.BindServiceFlags!, user: UserHandle! )`
`Int`	`checkCallingOrSelfPermission(permission: String!)`
`Int`	`checkCallingOrSelfUriPermission(uri: Uri!, modeFlags: Int)`
`IntArray<Int>!`	`checkCallingOrSelfUriPermissions( uris: (Mutable)List<Uri!>!, modeFlags: Int )`
`Int`	`checkCallingPermission(permission: String!)`
`Int`	`checkCallingUriPermission(uri: Uri!, modeFlags: Int)`
`IntArray<Int>!`	`checkCallingUriPermissions(uris: (Mutable)List<Uri!>!, modeFlags: Int)`
`Int`	`checkContentUriPermissionFull(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)`
`Int`	`checkPermission(permission: String!, pid: Int, uid: Int)`
`Int`	`checkSelfPermission(permission: String!)`
`Int`	`checkUriPermission(uri: Uri!, pid: Int, uid: Int, modeFlags: Int)`
`IntArray<Int>!`	`checkUriPermissions( uris: (Mutable)List<Uri!>!, pid: Int, uid: Int, modeFlags: Int )`
`Unit`	`clearWallpaper()` This function is deprecated.
`Context!`	`createAttributionContext(attributionTag: String!)`
`Context!`	`createConfigurationContext(overrideConfiguration: Configuration!)`
`Context!`	`createContext(contextParams: ContextParams!)`
`Context!`	`createContextForSplit(splitName: String!)`
`Context!`	`createDeviceContext(deviceId: Int)`
`Context!`	`createDeviceProtectedStorageContext()`
`Context!`	`createDisplayContext(display: Display!)`
`Context!`	`createPackageContext(packageName: String!, flags: Int)`
`Context!`	`createWindowContext(display: Display!, type: Int, options: Bundle!)`
`Array<String!>!`	`databaseList()`
`Boolean`	`deleteDatabase(name: String!)`
`Boolean`	`deleteFile(name: String!)`
`Boolean`	`deleteSharedPreferences(name: String!)`
`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!>!`	`fileList()`
`Context!`	`getApplicationContext()`
`ApplicationInfo!`	`getApplicationInfo()`
`AssetManager!`	`getAssets()`
`AttributionSource!`	`getAttributionSource()`
`String!`	`getAttributionTag()`
`Context!`	`getBaseContext()`
`File!`	`getCacheDir()`
`ClassLoader!`	`getClassLoader()`
`File!`	`getCodeCacheDir()`
`ContentResolver!`	`getContentResolver()`
`File!`	`getDataDir()`
`File!`	`getDatabasePath(name: String!)`
`Int`	`getDeviceId()`
`File!`	`getDir(name: String!, mode: Int)`
`Display!`	`getDisplay()`
`File!`	`getExternalCacheDir()`
`Array<File!>!`	`getExternalCacheDirs()`
`File!`	`getExternalFilesDir(type: String!)`
`Array<File!>!`	`getExternalFilesDirs(type: String!)`
`Array<File!>!`	`getExternalMediaDirs()` This function is deprecated.
`File!`	`getFileStreamPath(name: String!)`
`File!`	`getFilesDir()`
`Executor!`	`getMainExecutor()`
`Looper!`	`getMainLooper()`
`File!`	`getNoBackupFilesDir()`
`File!`	`getObbDir()`
`Array<File!>!`	`getObbDirs()`
`String!`	`getOpPackageName()`
`String!`	`getPackageCodePath()`
`PackageManager!`	`getPackageManager()`
`String!`	`getPackageName()`
`String!`	`getPackageResourcePath()`
`ContextParams!`	`getParams()`
`Resources!`	`getResources()`
`SharedPreferences!`	`getSharedPreferences(name: String!, mode: Int)`
`Any!`	`getSystemService(name: String!)`
`String!`	`getSystemServiceName(serviceClass: Class<Any!>!)`
`Resources.Theme!`	`getTheme()`
`Drawable!`	`getWallpaper()` This function is deprecated.
`Int`	`getWallpaperDesiredMinimumHeight()` This function is deprecated.
`Int`	`getWallpaperDesiredMinimumWidth()` This function is deprecated.
`Unit`	`grantUriPermission(toPackage: String!, uri: Uri!, modeFlags: Int)`
`Boolean`	`isDeviceProtectedStorage()`
`Boolean`	`isRestricted()`
`Boolean`	`isUiContext()`
`Boolean`	`moveDatabaseFrom(sourceContext: Context!, name: String!)`
`Boolean`	`moveSharedPreferencesFrom(sourceContext: Context!, name: String!)`
`FileInputStream!`	`openFileInput(name: String!)`
`FileOutputStream!`	`openFileOutput(name: String!, mode: Int)`
`SQLiteDatabase!`	`openOrCreateDatabase( name: String!, mode: Int, factory: SQLiteDatabase.CursorFactory! )`
`Drawable!`	`peekWallpaper()` This function is deprecated.
`Unit`	`registerComponentCallbacks(callback: ComponentCallbacks!)`
`Unit`	`registerDeviceIdChangeListener(executor: Executor!, listener: IntConsumer!)`
`Intent!`	`registerReceiver(receiver: BroadcastReceiver!, filter: IntentFilter!)`
`Unit`	`removeStickyBroadcast(intent: Intent!)` This function is deprecated.
`Unit`	`removeStickyBroadcastAsUser(intent: Intent!, user: UserHandle!)` This function is deprecated.
`Unit`	`revokeSelfPermissionsOnKill(permissions: (Mutable)Collection<String!>!)`
`Unit`	`revokeUriPermission(uri: Uri!, modeFlags: Int)`
`Unit`	`sendBroadcast(intent: Intent!)`
`Unit`	`sendBroadcastAsUser(intent: Intent!, user: UserHandle!)`
`Unit`	`sendOrderedBroadcast( intent: Intent!, initialCode: Int, receiverPermission: String!, receiverAppOp: String!, resultReceiver: BroadcastReceiver!, scheduler: Handler!, initialData: String!, initialExtras: Bundle!, options: Bundle! )`
`Unit`	`sendOrderedBroadcastAsUser( intent: Intent!, user: UserHandle!, receiverPermission: String!, resultReceiver: BroadcastReceiver!, scheduler: Handler!, initialCode: Int, initialData: String!, initialExtras: Bundle! )`
`Unit`	`sendStickyBroadcast(intent: Intent!)` This function is deprecated.
`Unit`	`sendStickyBroadcastAsUser(intent: Intent!, user: UserHandle!)` 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`	`startActivities(intents: Array<Intent!>!)`
`Unit`	`startActivity(intent: Intent!)`
`ComponentName!`	`startForegroundService(service: Intent!)`
`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`	`stopService(name: Intent!)`
`Unit`	`unbindService(conn: ServiceConnection!)`
`Unit`	`unregisterComponentCallbacks(callback: ComponentCallbacks!)`
`Unit`	`unregisterDeviceIdChangeListener(listener: IntConsumer!)`
`Unit`	`unregisterReceiver(receiver: BroadcastReceiver!)`
`Unit`	`updateServiceGroup(conn: ServiceConnection!, group: Int, importance: Int)`

From android.app.Service

`Unit`	`attachBaseContext(newBase: Context!)`
`Unit`	`dump(fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)`
`Application!`	`getApplication()`
`Int`	`getForegroundServiceType()`
`Unit`	`onConfigurationChanged(newConfig: Configuration!)`
`Unit`	`onLowMemory()` This function is deprecated.
`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`	`stopSelf()`
`Boolean`	`stopSelfResult(startId: Int)`

Constants

DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS

@UnstableApi
const val DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS = 600000: Long

The default timeout for a session to stay in a foreground service state after it paused, stopped, failed or ended.

SERVICE_INTERFACE

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

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

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_AFTER_STOP_OR_ERROR

@UnstableApi
const val SHOW_NOTIFICATION_FOR_IDLE_PLAYER_AFTER_STOP_OR_ERROR = 3: Int

Shows a notification when the Player is in STATE_IDLE due to stop or an error, has media, and the notification wasn't explicitly dismissed.

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_ALWAYS

@UnstableApi
const val SHOW_NOTIFICATION_FOR_IDLE_PLAYER_ALWAYS = 1: Int

Always show a notification when the Player is in STATE_IDLE, has media, and the notification wasn't explicitly dismissed.

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_NEVER

@UnstableApi
const val SHOW_NOTIFICATION_FOR_IDLE_PLAYER_NEVER = 2: Int

Never show a notification when the Player is in STATE_IDLE.

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 user-engaged playback that is run in a foreground service.

It is only possible to terminate the service with stopSelf if this method returns false.

Note that sessions are kept in foreground and this method returns true for the foreground service timeout after they paused, stopped, failed or ended. Use pauseAllPlayersAndStopSelf to pause all ongoing playbacks immediately and terminate the service.

This method must be called on the main thread.

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.

Note: This method must not be called directly by app code.

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

This method can be overridden to customize the behavior of when the app is dismissed from the recent apps.

The default behavior is that if playback is ongoing, which means the service is already running in the foreground, and at least one media session is playing, the service is kept running. Otherwise, playbacks are paused and the service is stopped by calling pauseAllPlayersAndStopSelf 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.

Note: This method must not be called directly by app code.

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, ensures the foreground service is stopped, and calls stopSelf.

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

This method must be called on the main thread.

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`

setForegroundServiceTimeoutMs

@UnstableApi
fun setForegroundServiceTimeoutMs(foregroundServiceTimeoutMs: Long): Unit

Sets the timeout for a session to stay in a foreground service state after it paused, stopped, failed or ended.

Can only be called once the Context of the service is initialized in onCreate.

Has no effect on already running timeouts.

The default and maximum value is DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS. If a larger value is provided, it will be clamped down to DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS.

This method must be called on the main thread.

Parameters
`foregroundServiceTimeoutMs: Long`	The timeout in milliseconds.

setListener

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

Sets the listener.

This method can be called from any thread.

setShowNotificationForIdlePlayer

@UnstableApi
fun setShowNotificationForIdlePlayer(
    @MediaSessionService.ShowNotificationForIdlePlayerMode showNotificationForIdlePlayerMode: Int
): Unit

Sets whether and when a notification for a Player in STATE_IDLE should be shown.

Parameters
`@MediaSessionService.ShowNotificationForIdlePlayerMode showNotificationForIdlePlayerMode: Int`	The `ShowNotificationForIdlePlayerMode`.

triggerNotificationUpdate

@UnstableApi
fun triggerNotificationUpdate(): Unit

Manually trigger a notification update.

In most cases, this should not be required unless an external event that can't be detected by the session itself requires to update the notification.

Protected functions

setMediaNotificationProvider

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

Sets the MediaNotification.Provider to customize notifications.

This method can be called from any thread.

MediaSessionService

Service Lifecycle

Supporting Multiple Sessions

Summary

Nested types

Constants

Public constructors

Public functions

Protected functions

Inherited Constants

Inherited functions

Constants

DEFAULT_FOREGROUND_SERVICE_TIMEOUT_MS

SERVICE_INTERFACE

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_AFTER_STOP_OR_ERROR

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_ALWAYS

SHOW_NOTIFICATION_FOR_IDLE_PLAYER_NEVER

Public constructors

MediaSessionService

Public functions

addSession

clearListener

getSessions

isPlaybackOngoing

isSessionAdded

onBind

onCreate

onDestroy

onGetSession

onStartCommand

onTaskRemoved

onUpdateNotification

onUpdateNotification

pauseAllPlayersAndStopSelf

removeSession

setForegroundServiceTimeoutMs

setListener

setShowNotificationForIdlePlayer

triggerNotificationUpdate

Protected functions

setMediaNotificationProvider