# MediaButtonReceiver

Artifact: [androidx.media:media](https://developer.android.com/jetpack/androidx/releases/media) [View Source](https://cs.android.com/search?q=file:androidx/media/session/MediaButtonReceiver.java+class:androidx.media.session.MediaButtonReceiver) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

*** ** * ** ***


```
public class MediaButtonReceiver extends BroadcastReceiver
```

<br />

|---|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object.html) |||
| ↳ | [android.content.BroadcastReceiver](https://developer.android.com/reference/android/content/BroadcastReceiver.html) ||
|   | ↳ | [androidx.media.session.MediaButtonReceiver](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver) |

*** ** * ** ***

> [!CAUTION]
> **This class is deprecated.**   
>
> androidx.media is deprecated. Please migrate to [androidx.media3](https://developer.android.com/media/media3).

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 `https://developer.android.com/reference/android/app/Service.html` in your app that controls media playback via a `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat`. Once a key event is received by MediaButtonReceiver, this class tries to find a `https://developer.android.com/reference/android/app/Service.html` that can handle `https://developer.android.com/reference/android/content/Intent.html#ACTION_MEDIA_BUTTON`, and a `https://developer.android.com/reference/androidx/media/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 `https://developer.android.com/reference/java/lang/IllegalStateException.html` 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 `https://developer.android.com/reference/android/content/Intent.html#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 `https://developer.android.com/reference/android/app/Service.html#onStartCommand(android.content.Intent, int, int)` by calling `https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#handleIntent(android.support.v4.media.session.MediaSessionCompat,android.content.Intent)`, passing in your current `https://developer.android.com/reference/android/support/v4/media/session/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 `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat.Callback` will be triggered based on the incoming `https://developer.android.com/reference/android/view/KeyEvent.html`.

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

#### MediaBrowserService

If you already have a `https://developer.android.com/reference/androidx/media/MediaBrowserServiceCompat` in your app, MediaButtonReceiver will deliver the received key events to the `https://developer.android.com/reference/androidx/media/MediaBrowserServiceCompat` by default. You can handle them in your `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat.Callback`.

## Summary

| ### Public constructors |
|---|
| `[MediaButtonReceiver](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#MediaButtonReceiver())()` **This method is deprecated.** Deprecated in Java |

| ### Public methods |
|---|---|
| `static https://developer.android.com/reference/android/app/PendingIntent.html` | `[buildMediaButtonPendingIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#buildMediaButtonPendingIntent(android.content.Context,long))(https://developer.android.com/reference/android/content/Context.html context, long action)` **This method is deprecated.** Deprecated in Java |
| `static https://developer.android.com/reference/android/app/PendingIntent.html` | `[buildMediaButtonPendingIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#buildMediaButtonPendingIntent(android.content.Context,android.content.ComponentName,long))( https://developer.android.com/reference/android/content/Context.html context, https://developer.android.com/reference/android/content/ComponentName.html mbrComponent, long action )` **This method is deprecated.** Deprecated in Java |
| `static https://developer.android.com/reference/android/view/KeyEvent.html` | `[handleIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#handleIntent(android.support.v4.media.session.MediaSessionCompat,android.content.Intent))(https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat mediaSessionCompat, https://developer.android.com/reference/android/content/Intent.html intent)` **This method is deprecated.** Deprecated in Java |
| `void` | `[onReceive](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#onReceive(android.content.Context,android.content.Intent))(https://developer.android.com/reference/android/content/Context.html context, https://developer.android.com/reference/android/content/Intent.html intent)` **This method is deprecated.** Deprecated in Java |

| ### Protected methods |
|---|---|
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 31) [onForegroundServiceStartNotAllowedException](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#onForegroundServiceStartNotAllowedException(android.content.Intent,android.app.ForegroundServiceStartNotAllowedException))( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/content/Intent.html intent, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/app/ForegroundServiceStartNotAllowedException.html e )` **This method is deprecated.** Deprecated in Java |

### Inherited methods

From [android.content.BroadcastReceiver](https://developer.android.com/reference/android/content/BroadcastReceiver.html) `final void` `[abortBroadcast](https://developer.android.com/reference/android/content/BroadcastReceiver.html#abortBroadcast())()`

**This method is deprecated.** Deprecated in Java
`final void` `[clearAbortBroadcast](https://developer.android.com/reference/android/content/BroadcastReceiver.html#clearAbortBroadcast())()`

**This method is deprecated.** Deprecated in Java
`final boolean` `[getAbortBroadcast](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getAbortBroadcast())()`

**This method is deprecated.** Deprecated in Java
`final boolean` `[getDebugUnregister](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getDebugUnregister())()`

**This method is deprecated.** Deprecated in Java
`final int` `[getResultCode](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getResultCode())()`

**This method is deprecated.** Deprecated in Java
`final https://developer.android.com/reference/java/lang/String.html` `[getResultData](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getResultData())()`

**This method is deprecated.** Deprecated in Java
`final https://developer.android.com/reference/android/os/Bundle.html` `[getResultExtras](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getResultExtras(boolean))(boolean makeMap)`

**This method is deprecated.** Deprecated in Java
`https://developer.android.com/reference/java/lang/String.html` `[getSentFromPackage](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getSentFromPackage())()`

**This method is deprecated.** Deprecated in Java
`int` `[getSentFromUid](https://developer.android.com/reference/android/content/BroadcastReceiver.html#getSentFromUid())()`

**This method is deprecated.** Deprecated in Java
`final https://developer.android.com/reference/android/content/BroadcastReceiver.PendingResult.html` `[goAsync](https://developer.android.com/reference/android/content/BroadcastReceiver.html#goAsync())()`

**This method is deprecated.** Deprecated in Java
`final boolean` `[isInitialStickyBroadcast](https://developer.android.com/reference/android/content/BroadcastReceiver.html#isInitialStickyBroadcast())()`

**This method is deprecated.** Deprecated in Java
`final boolean` `[isOrderedBroadcast](https://developer.android.com/reference/android/content/BroadcastReceiver.html#isOrderedBroadcast())()`

**This method is deprecated.** Deprecated in Java
`https://developer.android.com/reference/android/os/IBinder.html` `[peekService](https://developer.android.com/reference/android/content/BroadcastReceiver.html#peekService(android.content.Context, android.content.Intent))(https://developer.android.com/reference/android/content/Context.html myContext, https://developer.android.com/reference/android/content/Intent.html service)`

**This method is deprecated.** Deprecated in Java
`final void` `[setDebugUnregister](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setDebugUnregister(boolean))(boolean debug)`

**This method is deprecated.** Deprecated in Java
`final void` `[setOrderedHint](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setOrderedHint(boolean))(boolean isOrdered)`

**This method is deprecated.** Deprecated in Java
`final void` `[setResult](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setResult(int, java.lang.String, android.os.Bundle))(int code, https://developer.android.com/reference/java/lang/String.html data, https://developer.android.com/reference/android/os/Bundle.html extras)`

**This method is deprecated.** Deprecated in Java
`final void` `[setResultCode](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setResultCode(int))(int code)`

**This method is deprecated.** Deprecated in Java
`final void` `[setResultData](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setResultData(java.lang.String))(https://developer.android.com/reference/java/lang/String.html data)`

**This method is deprecated.** Deprecated in Java
`final void` `[setResultExtras](https://developer.android.com/reference/android/content/BroadcastReceiver.html#setResultExtras(android.os.Bundle))(https://developer.android.com/reference/android/os/Bundle.html extras)`

**This method is deprecated.** Deprecated in Java

## Public constructors

### MediaButtonReceiver

Added in 1.1.0 Deprecated in 1.8.0

```
public [MediaButtonReceiver](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#MediaButtonReceiver())()
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

## Public methods

### buildMediaButtonPendingIntent

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public static PendingIntent [buildMediaButtonPendingIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#buildMediaButtonPendingIntent(android.content.Context,long))(Context context, long action)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Creates a broadcast pending intent that will send a media button event. The `action` will be translated to the appropriate `https://developer.android.com/reference/android/view/KeyEvent.html`, and it will be sent to the registered media button receiver in the given context. The `action` should be one of the following:

- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PLAY()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PAUSE()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_SKIP_TO_NEXT()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_SKIP_TO_PREVIOUS()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_STOP()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_FAST_FORWARD()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_REWIND()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PLAY_PAUSE()`

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/content/Context.html context` | The context of the application. |
| `long action` | The action to be sent via the pending intent. |

| Returns |
|---|---|
| `https://developer.android.com/reference/android/app/PendingIntent.html` | 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](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public static PendingIntent [buildMediaButtonPendingIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#buildMediaButtonPendingIntent(android.content.Context,android.content.ComponentName,long))(
    Context context,
    ComponentName mbrComponent,
    long action
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Creates a broadcast pending intent that will send a media button event. The `action` will be translated to the appropriate `https://developer.android.com/reference/android/view/KeyEvent.html`, and sent to the provided media button receiver via the pending intent. The `action` should be one of the following:

- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PLAY()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PAUSE()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_SKIP_TO_NEXT()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_SKIP_TO_PREVIOUS()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_STOP()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_FAST_FORWARD()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_REWIND()`
- `https://developer.android.com/reference/android/support/v4/media/session/PlaybackStateCompat#ACTION_PLAY_PAUSE()`

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/content/Context.html context` | The context of the application. |
| `https://developer.android.com/reference/android/content/ComponentName.html 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 |
|---|---|
| `https://developer.android.com/reference/android/app/PendingIntent.html` | Created pending intent, or null if the given component name is null or the `action` is unsupported/invalid. |

### handleIntent

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public static KeyEvent [handleIntent](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#handleIntent(android.support.v4.media.session.MediaSessionCompat,android.content.Intent))(MediaSessionCompat mediaSessionCompat, Intent intent)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Extracts any available `https://developer.android.com/reference/android/view/KeyEvent.html` from an `https://developer.android.com/reference/android/content/Intent.html#ACTION_MEDIA_BUTTON` intent, passing it onto the `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat` using `https://developer.android.com/reference/android/support/v4/media/session/MediaControllerCompat#dispatchMediaButtonEvent(android.view.KeyEvent)`, which in turn will trigger callbacks to the `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat.Callback` registered via `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat#setCallback(android.support.v4.media.session.MediaSessionCompat.Callback)`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat mediaSessionCompat` | A `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat` that has a `https://developer.android.com/reference/android/support/v4/media/session/MediaSessionCompat.Callback` set. |
| `https://developer.android.com/reference/android/content/Intent.html intent` | The intent to parse. |

| Returns |
|---|---|
| `https://developer.android.com/reference/android/view/KeyEvent.html` | The extracted `https://developer.android.com/reference/android/view/KeyEvent.html` if found, or null. |

### onReceive

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public void [onReceive](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#onReceive(android.content.Context,android.content.Intent))(Context context, Intent intent)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

## Protected methods

### onForegroundServiceStartNotAllowedException

Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/media#1.7.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
@RequiresApi(value = 31)
protected void [onForegroundServiceStartNotAllowedException](https://developer.android.com/reference/androidx/media/session/MediaButtonReceiver#onForegroundServiceStartNotAllowedException(android.content.Intent,android.app.ForegroundServiceStartNotAllowedException))(
    @NonNull Intent intent,
    @NonNull ForegroundServiceStartNotAllowedException e
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

This method is called when an exception is thrown when calling `https://developer.android.com/reference/android/content/Context.html#startForegroundService(android.content.Intent)` 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 `https://developer.android.com/reference/android/content/Intent.html#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 `https://developer.android.com/reference/android/support/v4/media/MediaBrowserCompat` to bind to and start the service instead of broadcasting an intent.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/content/Intent.html intent` | The intent that was used `https://developer.android.com/reference/android/content/Context.html#startForegroundService(android.content.Intent)`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/app/ForegroundServiceStartNotAllowedException.html e` | The exception thrown by the system and caught by this broadcast receiver. |