MediaButtonReceiver

Artifact: androidx.media3:media3-session

View Source

---

Kotlin |Java

@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
MediaButtonReceiver()

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

Protected methods
void	@RequiresApi(value = 31) 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.

Inherited methods

From android.content.BroadcastReceiver final void abortBroadcast() final void clearAbortBroadcast() final boolean getAbortBroadcast() final boolean getDebugUnregister() final int getResultCode() final String getResultData() final Bundle getResultExtras(boolean makeMap) String getSentFromPackage() int getSentFromUid() final BroadcastReceiver.PendingResult goAsync() final boolean isInitialStickyBroadcast() final boolean isOrderedBroadcast() 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 setResultData(String data) final void setResultExtras(Bundle extras)

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.