added in version 24.1.0
belongs to Maven artifact


public class MediaButtonReceiver
extends BroadcastReceiver

   ↳ android.content.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="" >
     <action android:name="android.intent.action.MEDIA_BUTTON" />
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.


A service can receive a key event by including an intent filter that handles ACTION_MEDIA_BUTTON:
 <service android:name="" >
     <action android:name="android.intent.action.MEDIA_BUTTON" />
Events can then be handled in onStartCommand(Intent, int, int) by calling handleIntent(MediaSessionCompat, Intent), 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.


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.


Public constructors


Public methods

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

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

static PendingIntent buildMediaButtonPendingIntent(Context context, 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(KeyEvent), which in turn will trigger callbacks to the MediaSessionCompat.Callback registered via setCallback(MediaSessionCompat.Callback).

void onReceive(Context context, Intent intent)

Inherited methods

From class android.content.BroadcastReceiver