MediaButtonReceiver

@UnstableApi
class MediaButtonReceiver : BroadcastReceiver

kotlin.Any
   ↳ android.content.BroadcastReceiver
     ↳ androidx.media3.session.MediaButtonReceiver

A media button receiver receives hardware media playback button intent, such as those sent by wired and wireless headsets.

You can add this MediaButtonReceiver to your app by adding it directly to your AndroidManifest.xml: 

<receiver
    android:name="androidx.media3.session.MediaButtonReceiver"
    android:exported="true">
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</receiver>

Apps that add this receiver to the manifest, must implement onPlaybackResumption or active automatic playback resumption (Note: If you choose to make this receiver start your own service that is not a MediaSessionService or MediaLibraryService, then you need to fulfill all requirements around starting a service in the foreground on all API levels your app should properly work on).

Service discovery

This class assumes you have a Service in your app's manifest that controls media playback via a MediaSession. Once a key event is received by this receiver, it tries to find a Service that can handle the action ACTION_MEDIA_BUTTON, SERVICE_INTERFACE or SERVICE_INTERFACE. If an appropriate service is found, this class starts the service as a foreground service and sends the key event to the service by an Intent with action ACTION_MEDIA_BUTTON. If neither is available or more than one valid service is found for one of the actions, an is thrown.

Service handling ACTION_MEDIA_BUTTON

A service can receive a key event by including an intent filter that handles android.intent.action.MEDIA_BUTTON. 

<service android:name="com.example.android.MediaPlaybackService" >
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</service>

Service handling action MediaSessionService or MediaLibraryService

If you are using a MediaSessionService or MediaLibraryService, the service interface name is already used as the intent action. In this case, no further configuration is required. 

<service android:name="com.example.android.MediaPlaybackService" >
  <intent-filter>
    <action android:name="androidx.media3.session.MediaLibraryService" />
  </intent-filter>
</service>

Summary

Public constructors

Public functions
Unit
onReceive(context: Context!, intent: Intent?)

Protected functions
Unit

This method is called when an exception is thrown when calling startForegroundService as a result of receiving a media button event.
Boolean

Returns whether to start the media button event target service into the foreground.

Inherited functions
From android.content.BroadcastReceiver
Unit
Unit
Boolean
Boolean
Int
String!
Bundle!
String!
Int
BroadcastReceiver.PendingResult!
Boolean
Boolean
IBinder!
peekService(myContext: Context!, service: Intent!)
Unit
Unit
setOrderedHint(isOrdered: Boolean)
Unit
setResult(code: Int, data: String!, extras: Bundle!)
Unit
Unit
Unit

Public constructors

MediaButtonReceiver

MediaButtonReceiver()

Public functions

onReceive

fun onReceive(context: Context!, intent: Intent?): Unit

Protected functions

onForegroundServiceStartNotAllowedException

@RequiresApi(value = 31)
protected fun onForegroundServiceStartNotAllowedException(
    intent: Intent!,
    e: ForegroundServiceStartNotAllowedException!
): Unit

This method is called when an exception is thrown when calling startForegroundService as a result of receiving a media button event.

By default, this method only logs the exception and it can be safely overridden. Apps that find that such a media button event has been legitimately sent, may choose to override this method and take the opportunity to post a notification from where the user journey can continue.

This exception can be thrown if a broadcast media button event is received and a media service is found in the manifest that is registered to handle ACTION_MEDIA_BUTTON. If this happens on API 31+ and the app is in the background then an exception is thrown.

With the exception of devices that are running API 20 and below, a media button intent is only required to be sent to this receiver for a Bluetooth media button event that wants to restart the service. In such a case the app gets an exemption and is allowed to start the foreground service. In this case this method will never be called.

In all other cases of attempting to start a Media3 service or to send a media button event, apps must use a MediaBrowser or MediaController to bind to the service instead of broadcasting an intent.

Parameters
intent: Intent!

The intent that was used for starting the foreground service.
e: ForegroundServiceStartNotAllowedException!

The exception thrown by the system and caught by this broadcast receiver.

shouldStartForegroundService

protected fun shouldStartForegroundService(intent: Intent!): Boolean

Returns whether to start the media button event target service into the foreground.

Returns true by default. Apps can override this method to decide to not start a service when receiving an event with KEYCODE_MEDIA_PLAY or KEYCODE_MEDIA_PLAY_PAUSE that should be suppressed.

Note: Once the service is started into the foreground by the receiver, the app must start playback to get into the foreground or the system will crash the service with a ForegroundServiceDidNotStartInTimeException or an IllegalStateException.

Parameters
intent: Intent!

The intent that was received by the media button event receiver.
Returns
Boolean

true if the service should be started as a foreground service. If false is returned the service is not started and the receiver call is a no-op.