MediaButtonReceiver

public class MediaButtonReceiver extends BroadcastReceiver


A media button receiver receives and helps translate hardware media playback buttons, such as those found on wired and wireless headsets, into the appropriate callbacks in your app.

You can add this MediaButtonReceiver to your app by adding it directly to your AndroidManifest.xml:
<receiver android:name="androidx.media.session.MediaButtonReceiver" >
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</receiver>
This class assumes you have a Service in your app that controls media playback via a MediaSessionCompat. Once a key event is received by MediaButtonReceiver, this class tries to find a Service that can handle ACTION_MEDIA_BUTTON, and a MediaBrowserServiceCompat in turn. If an appropriate service is found, this class forwards the key event to the service. If neither is available or more than one valid service/media browser service is found, an IllegalStateException will be thrown. Thus, your app should have one of the following services to get a key event properly. Service Handling ACTION_MEDIA_BUTTON A service can receive a key event by including an intent filter that handles ACTION_MEDIA_BUTTON:
<service android:name="com.example.android.MediaPlaybackService" >
  <intent-filter>
    <action android:name="android.intent.action.MEDIA_BUTTON" />
  </intent-filter>
</service>
Events can then be handled in onStartCommand by calling handleIntent, passing in your current MediaSessionCompat:
private MediaSessionCompat mMediaSessionCompat = ...;

public int onStartCommand(Intent intent, int flags, int startId) {
  MediaButtonReceiver.handleIntent(mMediaSessionCompat, intent);
  return super.onStartCommand(intent, flags, startId);
}
This ensures that the correct callbacks to MediaSessionCompat.Callback will be triggered based on the incoming KeyEvent.

Note: Once the service is started, it must start to run in the foreground.

MediaBrowserService If you already have a MediaBrowserServiceCompat in your app, MediaButtonReceiver will deliver the received key events to the MediaBrowserServiceCompat by default. You can handle them in your MediaSessionCompat.Callback.

Summary

Public constructors

Public methods

static PendingIntent
buildMediaButtonPendingIntent(Context context, long action)

Creates a broadcast pending intent that will send a media button event.

static PendingIntent
buildMediaButtonPendingIntent(
    Context context,
    ComponentName mbrComponent,
    long action
)

Creates a broadcast pending intent that will send a media button event.

static KeyEvent
handleIntent(MediaSessionCompat mediaSessionCompat, Intent intent)

Extracts any available KeyEvent from an ACTION_MEDIA_BUTTON intent, passing it onto the MediaSessionCompat using dispatchMediaButtonEvent, which in turn will trigger callbacks to the MediaSessionCompat.Callback registered via setCallback.

void
onReceive(Context context, 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.

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

Added in 1.1.0
public MediaButtonReceiver()

Public methods

buildMediaButtonPendingIntent

Added in 1.1.0
public static PendingIntent buildMediaButtonPendingIntent(Context context, long action)

Creates a broadcast pending intent that will send a media button event. The action will be translated to the appropriate KeyEvent, and it will be sent to the registered media button receiver in the given context. The action should be one of the following:

Parameters
Context context

The context of the application.

long action

The action to be sent via the pending intent.

Returns
PendingIntent

Created pending intent, or null if cannot find a unique registered media button receiver or if the action is unsupported/invalid.

buildMediaButtonPendingIntent

Added in 1.1.0
public static PendingIntent buildMediaButtonPendingIntent(
    Context context,
    ComponentName mbrComponent,
    long action
)

Creates a broadcast pending intent that will send a media button event. The action will be translated to the appropriate KeyEvent, and sent to the provided media button receiver via the pending intent. The action should be one of the following:

Parameters
Context context

The context of the application.

ComponentName mbrComponent

The full component name of a media button receiver where you want to send this intent.

long action

The action to be sent via the pending intent.

Returns
PendingIntent

Created pending intent, or null if the given component name is null or the action is unsupported/invalid.

handleIntent

Added in 1.1.0
public static KeyEvent handleIntent(MediaSessionCompat mediaSessionCompat, Intent intent)

Extracts any available KeyEvent from an ACTION_MEDIA_BUTTON intent, passing it onto the MediaSessionCompat using dispatchMediaButtonEvent, which in turn will trigger callbacks to the MediaSessionCompat.Callback registered via setCallback.

Parameters
MediaSessionCompat mediaSessionCompat

A MediaSessionCompat that has a MediaSessionCompat.Callback set.

Intent intent

The intent to parse.

Returns
KeyEvent

The extracted KeyEvent if found, or null.

onReceive

Added in 1.1.0
public void onReceive(Context context, Intent intent)

Protected methods

onForegroundServiceStartNotAllowedException

Added in 1.7.0
@RequiresApi(value = 31)
protected void onForegroundServiceStartNotAllowedException(
    @NonNull Intent intent,
    @NonNull 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.

Normally, a media button intent should only be required to be sent by the system in case of a Bluetooth media button event that wants to restart the app. However, 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, apps should use a media browser to bind to and start the service instead of broadcasting an intent.

Parameters
@NonNull Intent intent

The intent that was used for starting the foreground service.

@NonNull ForegroundServiceStartNotAllowedException e

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