MediaButtonReceiver

@UnstableApi
public class MediaButtonReceiver extends BroadcastReceiver

java.lang.Object
   ↳ 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 methods
final void
onReceive(Context context, @Nullable Intent intent)

Protected methods
void

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 methods
From android.content.BroadcastReceiver
final void
final void
final boolean
final boolean
final int
final String
final Bundle
getResultExtras(boolean makeMap)
String
int
final BroadcastReceiver.PendingResult
final boolean
final boolean
IBinder
peekService(Context myContext, Intent service)
final void
setDebugUnregister(boolean debug)
final void
setOrderedHint(boolean isOrdered)
final void
setResult(int code, String data, Bundle extras)
final void
setResultCode(int code)
final void
final void

Public constructors

MediaButtonReceiver

public MediaButtonReceiver()

Public methods

onReceive

public final void onReceive(Context context, @Nullable Intent intent)

Protected methods

onForegroundServiceStartNotAllowedException

@RequiresApi(value = 31)
protected void onForegroundServiceStartNotAllowedException(
    Intent intent,
    ForegroundServiceStartNotAllowedException e
)

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.
ForegroundServiceStartNotAllowedException e

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

shouldStartForegroundService

protected boolean shouldStartForegroundService(Intent intent)

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.