Media buttons in notification

[at-oliverapps]

i would like to know how to customize the notification in media 3 like shown in pictures below

Expected behavior how it was before with PlayerNotificationManager

how it is now with media3

[marcbaechinger]

PlayerNotificationManager does not work together with Android 13 out of the box. If you want to customize the notification to get a notification as above you can implement a CustomLayout that defines the custom commands that should be displayed on the mini player/media notification.

There is issue #38 that explains how a custom layout can be done that provides a notification across all API levels.

You can use DefaultMediaNotificationProvider to tune the look of the notification on API levels lower than 33 (see JavaDoc and please see #213 that is fixed on the main branch).

You may want to consult the Android 13 documentation on how custom actions are used to layout the new miniplayer.
https://developer.android.com/about/versions/13/behavior-changes-13#playback-controls

[at-oliverapps]

hello Marc thanks for reaching back to me
first 2 pics is with Media3 and below is PlayerNotificationManager
im using media3 now and I like it but I have these problems

I tried searching around and I can't seem to figure out how to make it work on my own I even looked at the documentation and in sourcecode for DefaultMediaNotificationProvider
its described how to get it appear in miniplayer but not how to make ( PREV : PLAY_PAUSE : NEXT ) appear in miniplayer below android 13

and can't figure out to replace (play next prev) icons in android 13 I know Spotify did it and it works for me below android 13
is it how it is in android 13+

[marcbaechinger]

EDIT: Since this comment was written, Media3 has introduced an API throught the media notification controller, which is now the preferred way to remove player commands for the media notification. Using a ForwardingPlayer is discouraged as it has the disadvantage to remove the command on the player level and hence for all controllers.

See also Android Media Controls.

---

Yeah, it's complicated. Please accept my apologies that this is not documented properly yet. We need to provide this asap because it is complicated. I added the documentation candidate labels to express this.

Let me try to give an overview/introduction:

1. All screenshots above are mini players based on the actions that are added to the notification. These are PendingIntent that will be sent to the service when tapped. These kind of notifications are displayed on all devices with Android 12 and earlier. They are also shown like this for apps that are running on an Android 13 device but still have the targetSdk set to below 33. I think this is the case for your app, that's why even on Android 13 it is handled like for Android 12 and before.

2. For all these cases (Android 12 and earlier and apps with targetSdk below 33), by default, the DefaultMediaNotificationProvider adds all the player commands first and then the custom layout. I think that's how you end up with this:

You can change the order of the actions by creating your own MediaNotificationProvider that is a sublcass of DefaultMediaNotifcationProvider and then override getMediaButtons(). However, there is a bug #213 that is fixed on the main branch but not yet release. This prevents you from subclassing the DefaultMediaNotificationProvider with the current released version I'm afraid.

With the fix of #213 this lets you create the notifications for API level <33 as you like I think.

3. On Android 13 and with targetSdk=33, the mini player is based on the actions and custom actions that are present in the PlaybackStateCompat of the media session as opposed to the actions of the notification. It looks like this (note the big play/pause button)

Because it is not based on the notification but on the PlaybackStateCompat the order of the elements is different. By default the custom actions are placed to the right (see the crossed arrow shuffle icon to the right which is a custom command that is added to the CustomLayout as described in #38).

It's possible to hide the skip previous and skip next button by removing the available commands Player.COMMAND_SEEK_TO_PREVIOUS and Player.COMMAND_SEEK_TO_NEXT from the player that is used when building the MediaSession in Media3:

val player =
      ExoPlayer.Builder(this)
        .setAudioAttributes(AudioAttributes.DEFAULT, /* handleAudioFocus= */ true)
        .build()

val forwardingPlayer =
      object : ForwardingPlayer(player) {
        override fun getAvailableCommands(): Player.Commands {
          return super.getAvailableCommands()
                  .buildUpon()
                  .remove(COMMAND_SEEK_TO_PREVIOUS)
                  .remove(COMMAND_SEEK_TO_NEXT)
                  .build()
        }
      }
MediaSession.Builder(context, forwardingPlayer)
    .build()

Now, the skip previous and the skip next button would not be displayed in the mini player. Instead the custom actions are placed at these positions. So in the screenshot above the shuffle icon would be at the position of the skip previous button. With this we can for instance provide three custom commands in the CustomLayout like:

[[rewind 30s], [ffwd 30s], [shuffle]]

Now, the rewind 30s is to the left of the seek bar, ffwd 30s is to the right of the seekbar, and all the other custom commands follow to the right.

EDIT: I don't think this last section is correct, sorry. This is currently not supported with Media3

However, some apps probably do not want that. So we can advice the mini player to simply space out the skip to previous/skip to next buttons and leave them empty, and put the custom command as the are in the screenshot above (usually only one is displayed). To signal this an app needs to set some session extras right after building the session:

val sessionExtras = Bundle()
sessionExtras.putBoolean(MediaConstants.EXTRAS_KEY_SLOT_RESERVATION_SEEK_TO_PREV, true);
sessionExtras.putBoolean(MediaConstants.EXTRAS_KEY_SLOT_RESERVATION_SEEK_TO_NEXT, true);
mediaSession.setSessionExtras(sessionExtras)

[PaulWoitaschek]

I'm also having a really hard time figuring this out.
I'm developing an audiobook player so the hard fast forward / rewind do not make sense at all.

However I still need them to be supported because if for example a user presses next / previous through a bluetooth headset gesture I need to handle that as a fast forward / rewind instead.

I achieved that by overwriting the commands in my wrapping player:

  override fun seekToPreviousMediaItem() {
    seekBack()
  }

  override fun seekToPrevious() {
    seekBack()
  }

  override fun seekToNext() {
    seekForward()
  }

  override fun seekToNextMediaItem() {
    seekForward()
  }

Setting EXTRAS_KEY_SLOT_RESERVATION_SEEK_TO_PREV does / NEXT does not seem to have any effect.

Right now I could get two things to work:

1. Advertise the default commands and overwriting their actions. This has the disadvantage that in the Android 13 Notification, the previous / next icons are shown instead of the fast forward / rewind icons.
2. Remove the next / previous from the available commands. This leads to my custom fast forward / rewind being shown. So from the UI everything is perfect. This however now breaks the ability to control the fast forward / rewind using bluetooth headset taps.

Is there any way to fix this?

[maknon]

val player =
      ExoPlayer.Builder(this)
        .setAudioAttributes(AudioAttributes.DEFAULT, /* handleAudioFocus= */ true)
        .build()

val forwardingPlayer =
      object : ForwardingPlayer(player) {
        override fun getAvailableCommands(): Player.Commands {
          return super.getAvailableCommands()
                  .buildUpon()
                  .remove(COMMAND_SEEK_TO_PREVIOUS)
                  .remove(COMMAND_SEEK_TO_NEXT)
                  .build()
        }
      }
MediaSession.Builder(context, forwardingPlayer)
    .build()

Now, the skip previous and the skip next button would not be displayed in the mini player

if i have more than one MediaItem, the button is displayed but do nothing if clicked when trying to use this code. is this a bug or an intended behavior ?

[brabebhin]

I managed to obtain the first expected screenshot by using this media notification builder implementation. My aim was to have all 3 buttons (skip previous, play/pause, skip next) shown in compact mode on both android 12 and 13, as shown in the first screenshot

My guess is that further customization can be done with addNotificationActions. Maybe this can further help people who also run into this issue.

class MediaNotificationBuilder(val context: Context) : DefaultMediaNotificationProvider(context) {

override fun addNotificationActions(
    mediaSession: MediaSession,
    mediaButtons: MutableList<CommandButton>,
    builder: NotificationCompat.Builder,
    actionFactory: MediaNotification.ActionFactory
): IntArray {

    val skipPreviousCommandButton = CommandButton.Builder().setPlayerCommand(COMMAND_SEEK_TO_PREVIOUS).setEnabled(true).setIconResId(androidx.media3.ui.R.drawable.exo_ic_skip_previous)
        .setExtras(Bundle().apply { putInt("androidx.media3.session.command.COMPACT_VIEW_INDEX", 0)}).build();

    val playCommandButton = CommandButton.Builder().setPlayerCommand(COMMAND_PLAY_PAUSE).setEnabled(true).setIconResId(if(mediaSession.player.isPlaying) androidx.media3.ui.R.drawable.exo_icon_pause else androidx.media3.ui.R.drawable.exo_icon_play)
        .setExtras(Bundle().apply { putInt("androidx.media3.session.command.COMPACT_VIEW_INDEX", 1)}).build();

    val skipNextCommandButton = CommandButton.Builder().setPlayerCommand(COMMAND_SEEK_TO_NEXT).setEnabled(true).setIconResId(androidx.media3.ui.R.drawable.exo_ic_skip_next)
        .setExtras(Bundle().apply { putInt("androidx.media3.session.command.COMPACT_VIEW_INDEX", 2)}).build();

    mediaButtons.clear()
    mediaButtons.add(skipPreviousCommandButton)
    mediaButtons.add(playCommandButton)
    mediaButtons.add(skipNextCommandButton)

    return super.addNotificationActions(mediaSession, mediaButtons, builder, actionFactory)
}

}

[marcbaechinger]

Thanks for the snippet @brabebhin

If you override DefaultMediaNotificationProvider.getMediaButtons(...) and then return that list of buttons that you create above, would that be the same? The list would then be the argument mediaButtons in addNotificationActions(...). That's how the API was designed. Sorry for this not being documented yet besides the JavaDoc. Documentation work has been started and is on it's way.

[brabebhin]

This is for beta2. In beta3 it is no longer possible to derive DefaultMediaNotificationProvider, as I just tried right now.

The problem with getMediaButtons (assuming the inability to override is another bug) is that you can't get to know which is the playback state of the player. You could theoretically pass the player instance to the constructor of the provider, but that is also ugly.

And since addNotificationActions allow you to override that list that you get as parameter, this is how I got it to work properly. In fact, I could simply create a new list there with the buttons and add them to the new list instead of using the one passed as parameter, but I was too lazy to do it.

My sugestions:

Pass the session instance that you get in addNotificationActions to getMediaButtons as well. This allows access to the player instance and allows better customization.
Make DefaultMediaNotificationProvider constructors public again, to allow overriding.
Make the list of media actions that you get in addNotificationActios immutable, to clarify the usage of the API.

You should regard documentation as an overhead. Make the API more intuitive by using the tools available to simply guide developers on the right path.
E.G. Documentation says the constructor is public, but in reality it is not.

[marcbaechinger]

Yes, sorry, my bad. The public constructors are already added in the main branch and this will be part of the next release that we are currently preparing (see #213).

I mark this issue as a bug to add the session like for addNotificationActions(..).

[imansdn]

Hi do we have any update for this?
I've been facing same challenges with Media3 recently, and I could really use some help. To give you a brief overview, I migrated our app from ExoPlayer to Media3 and followed Google's migration guide. However, it appears that there's no straightforward way to handle MediaButton KeyEvent actions manually.
I've been trying to find a solution, but so far, I haven't been successful.
I tried to elaborate my question in in this post

I'd greatly appreciate any insights or suggestions you may have on how to handle MediaButton actions manually with Media3.

Thanks

[marcbaechinger]

I'm not quite sure how your question is related to this issue. I think #249 may be more interesting for you.

It appears that there's no straightforward way to handle MediaButton KeyEvent actions manually.

That's true. I think you shouldn't focus on media button events, but instead solve your problem with the Media3 API. Besides Bluetooth, media button events are only a thing for actions coming from the notification below API 33. I wouldn't recommend going on this rather lower-level API because on API 33 and above the notification sends commands directly to the session without using media button events.

MediaButton events coming from a Bluetooth device are delivered by the system to the platform media session that delegates them to onMediaButtonEvent of the MediaSession.Callback and then delegates to MediaSessionCompat.Callback.onSkipToNext(). That's where Media3 receives it after the media button event has been resolved by the platform session to the specific callback method onSkipToNext:

onSkipToNext:455, MediaSessionLegacyStub (androidx.media3.session)
onSkipToNext:1691, MediaSessionCompat$Callback$MediaSessionCallbackApi21 (android.support.v4.media.session)
onMediaButtonEvent:967, MediaSession$Callback (android.media.session)
onMediaButtonEvent:1611, MediaSessionCompat$Callback$MediaSessionCallbackApi21 (android.support.v4.media.session)
handleMessage:1593, MediaSession$CallbackMessageHandler (android.media.session)
dispatchMessage:106, Handler (android.os)
loopOnce:201, Looper (android.os)
loop:288, Looper (android.os)
main:7884, ActivityThread (android.app)
invoke:-1, Method (java.lang.reflect)
run:548, RuntimeInit$MethodAndArgsCaller (com.android.internal.os)
main:936, ZygoteInit (com.android.internal.os)

Media3 then delegates the event to the player.

I'm not quite sure why you are trying to intercept media button events from your question. I assume you want to intercept commands coming from a BT headset.

If I'm right, then you can try to wrap the player in a ForwardingPlayer before you pass it to the Builder with which you build your session. This is an approach where you don't have to care about API levels or similar:

val forwardingPlayer =
  object : ForwardingPlayer(player) {

    override fun seekToPrevious() {
      val packageName = mediaLibrarySession.controllerForCurrentRequest?.packageName
      if (packageName == "com.google.android.bluetooth") {
        previousSegment()
        return;
      }
      super.seekToPrevious()
    }

    override fun seekToNext() {
      val packageName = mediaLibrarySession.controllerForCurrentRequest?.packageName
      if (packageName == "com.google.android.bluetooth") {
        nextSegment()
        return;
      }
      super.seekToNext()
    }
  }

mediaLibrarySession =
  MediaLibrarySession.Builder(this, forwardingPlayer, librarySessionCallback)
    .build()

session.controllerForCurrentRequest is the controller that sent the command and you can filter this way to only change the behavior for Bluetooth. If you want to change this behavior generally, you obviously don't need this check.

Can you try if this is an approach that would work for you?

[Shabinder]

I only play one media item at a time, however I need to show skip to next / skip to prev button and handle them manually.
Could use a forwarding player to intercept the command but I couldnt find a way to show skip to next and prev buttons without building a playlist in exoplayer.

Any advice on this ?

[marcbaechinger]

Have you tried overriding getAvailableCommands() and isCommandAvailable(int command) with your ForwardingPlayer and then make sure COMMAND_SEEK_TO_NEXT and COMMAND_SEEK_TO_PREVIOUS is always available? If the command is available, the button is drawn by the notification.

[Shabinder]

Forgot to update it here, but earlier I tried this and shipped the new release of my app with above change only.
Thanks @marcbaechinger .

[ygormsantos]

I was able to hide the buttons I didn't want overriding getAvailableCommands. Now I'm implementing seek for the current MediaItem.

Is there a way to enable this command without adding it to the notification?

[panzhiev]

@marcbaechinger Hi! I ran into a problem with my app intercepting media actions from the mini player (media notification) and headphones. The problem is that ExoPlayer and its setup is on the side of the sdk I'm using (so I can't use ForwardingPlayer for this purpose), while the MediaSessionService is on the client side. Each time, before the user presses the PLAY button, I need to check some conditions on the client - and only then pass (or not pass) this event to the player. In the case of the mini player, I did not find a way to intercept pressing the PLAY / PAUSE button in the notification. I tried to do it via onStartCommand of my service by KeyCode but it looks like a hack. Perhaps there is a more elegant way to intercept this event?

[marcbaechinger]

I think the best would be if the SDK provides you some API for this. If an SDK is burrying the API provided by a library that they wrap then I think the SDK should be in charge to either provide a way to integrate differently or expose the existing API to not restrict their users.

So the ForwardingPlayer is indeed what you should be able to do. Because the notification sends playback commands via PendingIntent or directly to the session depending on the API level. Overriding onStartCommand only gives you the commands below API 33. You also don't receive media button events on API 26 and later that for instance are coming from a Bluetooth events. The system sends these directly to the session as well. All of these eventuality arrive at the ForwardingPlayer. That's why this is the solution.

user presses the PLAY button, I need to check some conditions on the client - and only then pass (or not pass) this event to the player.

I don't think this is a good idea, because in the case of PLAY commands, the service is expected to be put in the foreground. Media3 puts the service in the foreground when the player is playing. So if you intercept the wrong Play event, then your app may crash with a ForegroundServiceDidNotStartInTimeException on API 31 and higher. See #167 for more details.

I'm not sure about your use case, but regarding Play commands, it's better to make sure that a given sender does not have an option to send the play command (like not showing a Play button). Once the command is sent, it's probably too late because it's risky to stop a Play command and turn it into a no-op for the reasons given above.

[phcannesson]

If I may add, one very common use-case where I would want to detect clicks on the notification is analytics.
Knowing if a next action comes from the app, the media controls or elsewhere.

[marcbaechinger]

@phcannesson

If I may add, one very common use-case where I would want to detect clicks on the notification is analytics.

In the main branch we added a method MediaSession.isMediaNotificationController(controllerInfo). Starting with the next release 1.2.0, an app can recognize whether a player command or a custom command is coming from the notification with this method:

val forwardingPlayer = object: ForwardingPlayer(player) {
      override fun play() {
        val controller = mediaLibrarySession.controllerForCurrentRequest
        controller?.let {
          if (mediaLibrarySession.isMediaNotificationController(controller)) {
            // handle command coming from media notification
          } 
        }
        super.play()
      }
    }

This sounds like would be useful for your use case of analytics. Media3 makes sure that the calling controller is always the same on all API levels. Under the hood, the commands can come from a PendingIntent or sent directly to the session starting with API 33. However, Media3 makes sure it always has the same calling controller that you can recognize with this helper method conveniently.

[k-arabadzhiev]

I had to customize the SEEK_TO_PREVIOUS/SEEK_TO_NEXT icons for notification player and looking at this issue (and some others) I've come to a conclusion that I need to add custom session commands AND also remove the player commands (COMMAND_SEEK_TO_PREVIOUS, COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM, COMMAND_SEEK_TO_NEXT, COMMAND_SEEK_TO_NEXT_MEDIA_ITEM) so they don't show in the notification.

In my case I have to have different buttons in the notification depending on the type of media that is currently playing (i.e. live media shouldn't have seek forward or back, only play/pause)

So I though the best place for me to change the commands is in MediaLibrarySession.Callback.onGetItem (I'm open to criticism, if this is not correct):

override fun onGetItem(
    session: MediaLibrarySession,
    browser: MediaSession.ControllerInfo,
    mediaId: String
): ListenableFuture<LibraryResult<MediaItem>> {
    // for versions below Android 13 I have CustomMediaNotificationProvider, 
    // extending DefaultMediaNotificationProvider with overriden getMediaButtons method
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (mediaItem.isLive) {
            session.mediaNotificationControllerInfo?.let {
                session.setAvailableCommands(
                    it,
                    MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS,
                    MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS
                )
            }
        } else {
            val availableSessionCommands =
                MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon()
            notificationPlayerCustomCommandButtons.forEach { commandButton ->
                commandButton.sessionCommand?.let { availableSessionCommands.add(it) }
            }
            val playerCommands =
                MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS.buildUpon()
                    .removeAll(
                        COMMAND_SEEK_TO_PREVIOUS,
                        COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM,
                        COMMAND_SEEK_TO_NEXT,
                        COMMAND_SEEK_TO_NEXT_MEDIA_ITEM,
                    ).build()
            session.mediaNotificationControllerInfo?.let {
                session.setAvailableCommands(
                    it,
                    availableSessionCommands.build(),
                    playerCommands
                )
            }
        }
    }
    LibraryResult.ofItem(
        mediaItem,
        LibraryParams.Builder().build()
    )
}

And then in onCustomCommand I can make everything work as expected:

override fun onCustomCommand(
    session: MediaSession,
    controller: MediaSession.ControllerInfo,
    customCommand: SessionCommand,
    args: Bundle
): ListenableFuture<SessionResult> {
    if (customCommand.customAction == NotificationPlayerCustomCommand.PREVIOUS.customAction) {
        session.player.seekToPrevious()
    }
    // other custom commands
    return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
}

However, what I don't understand and I find really counterintuitive is why does this even work? To be more specific, why is this line working:

session.player.seekToPrevious()

if the underlying player command has been removed? Even the documentation for seekToPrevious mentions:

This method must only be called if COMMAND_SEEK_TO_PREVIOUS is available.

[marcbaechinger]

me to change the commands is in MediaLibrarySession.Callback.onGetItem

onGetItem being called is not related to what is currently in the player. It probably works for your specific app in case you are using this method before setting the item to the player, but from the library side there is not relationship between onGetItem and what is playing.

I would recommend listening to Player.Listener.onMediaItemTransitioned instead. That is the event that is emitted by the player when the item currently being played changed. That's when you want to customize the notification for that item I think and independent from how this media item is set into the player. You want to listen to the result, not the action that triggers this result.

if the underlying player command has been removed? Even the documentation for seekToPrevious mentions:

Your code removes the commands from a specific controller, not from the player. While the controller can't send the command and the session would drop it if it arrives, the player can still do everything if an app wants it.

This only removes the command from the controller. I think this is correct and works as intended:

session.mediaNotificationControllerInfo?.let {
    session.setAvailableCommands(
        it,
        availableSessionCommands.build(),
        playerCommands
    )
}

It's a common scenario that you may want to have different commands available for different controllers. You only remove this from the controller, so that that specific controller can't send such a command. However, under the hood you as the app should still be able to call every command on the actual player. Else removing a command on controller A would disallow calling such a method for all controller, which is not intended.

[k-arabadzhiev]

I would recommend listening to Player.Listener.onMediaItemTransitioned instead

Thanks! I'll check how to do it using this method.

Your code removes the commands from a specific controller, not from the player

Oh yeah right I'm only changing the notification controller, my bad. Really silly to not notice that's how it works, when it's kinda obvious now. Thanks!

It's a common scenario that you may want to have different commands available for different controllers.

Indeed, that's what I'm doing right now actually and I think it finally clicked after reading your comment.

[marcbaechinger]

Ok, cool. Thanks for confirming.

I'm actually going to close this issue. Mostly because it has diverged a bit from the initial report that looks answered. The conversations here are not easily to find under this broad umbrella bug. :)

Don't hesitate to open a new issue with a more specific subject, if you have further questions. Happy to help!