DefaultMediaNotificationProvider

@UnstableApi
public class DefaultMediaNotificationProvider implements MediaNotification.Provider

The default MediaNotification.Provider.

Actions

The following actions are included in the provided notifications:

Custom commands

Custom actions are sent to the session under the hood. You can receive them by overriding the session callback method onCustomCommand. This is useful because starting with Android 13, the System UI notification sends commands directly to the session. So handling the custom commands on the session level allows you to handle them at the same callback for all API levels.

Drawables

The drawables used can be overridden by drawables with the same file names in res/drawables of the application module. Alternatively, you can override the drawable resource ID with a drawable element in a resource file in res/values. The drawable resource IDs are:
  • media3_notification_play - The play icon.
  • media3_notification_pause - The pause icon.
  • media3_notification_seek_to_previous - The previous icon.
  • media3_notification_seek_to_next - The next icon.
  • media3_notification_small_icon - The small icon. A different icon can be set with setSmallIcon.

String resources

String resources used can be overridden by resources with the same resource IDs defined by the application. The string resource IDs are:
  • media3_controls_play_description - The description of the play icon.
  • media3_controls_pause_description - The description of the pause icon.
  • media3_controls_seek_to_previous_description - The description of the previous icon.
  • media3_controls_seek_to_next_description - The description of the next icon.
  • default_notification_channel_name The name of the on which created notifications are posted. A different string resource can be set when constructing the provider with setChannelName.

Summary

Nested types

A builder for DefaultMediaNotificationProvider instances.

Provides notification IDs for posting media notifications for given media sessions.

Constants
static final String
COMMAND_KEY_COMPACT_VIEW_INDEX = "androidx.media3.session.command.COMPACT_VIEW_INDEX"

An extras key that can be used to define the index of a CommandButton in compact view.
static final String
DEFAULT_CHANNEL_ID = "default_channel_id"

The default ID used for the NotificationChannel on which created notifications are posted on.
static final @StringRes int

The default name used for the NotificationChannel on which created notifications are posted on.
static final int

The default ID used for the notificationId.
static final String
GROUP_KEY = "media3_group_key"

The group key used for the setGroup to avoid the media notification being auto-grouped with the other notifications.

Public constructors

Creates an instance.
DefaultMediaNotificationProvider(
    Context context,
    DefaultMediaNotificationProvider.NotificationIdProvider notificationIdProvider,
    String channelId,
    int channelNameResourceId
)

Creates an instance.

Public methods
final MediaNotification
createNotification(
    MediaSession mediaSession,
    ImmutableList<CommandButton> customLayout,
    MediaNotification.ActionFactory actionFactory,
    MediaNotification.Provider.Callback onNotificationChangedCallback
)

Creates a new MediaNotification.
final boolean
handleCustomCommand(MediaSession session, String action, Bundle extras)

Handles a notification's custom command.
final void
setSmallIcon(@DrawableRes int smallIconResourceId)

Sets the small icon of the notification which is also shown in the system status bar.

Protected methods
int[]
addNotificationActions(
    MediaSession mediaSession,
    ImmutableList<CommandButton> mediaButtons,
    NotificationCompat.Builder builder,
    MediaNotification.ActionFactory actionFactory
)

Adds the media buttons to the notification builder for the given action factory.
ImmutableList<CommandButton>
getMediaButtons(
    MediaSession session,
    Player.Commands playerCommands,
    ImmutableList<CommandButton> customLayout,
    boolean showPauseButton
)

Returns the ordered list of command buttons to be used to build the notification.
@Nullable CharSequence

Returns the content text to be used to build the notification.
@Nullable CharSequence

Returns the content title to be used to build the notification.

Constants

COMMAND_KEY_COMPACT_VIEW_INDEX

public static final String COMMAND_KEY_COMPACT_VIEW_INDEX = "androidx.media3.session.command.COMPACT_VIEW_INDEX"

An extras key that can be used to define the index of a CommandButton in compact view.

DEFAULT_CHANNEL_ID

public static final String DEFAULT_CHANNEL_ID = "default_channel_id"

The default ID used for the NotificationChannel on which created notifications are posted on.

DEFAULT_CHANNEL_NAME_RESOURCE_ID

public static final @StringRes int DEFAULT_CHANNEL_NAME_RESOURCE_ID

The default name used for the NotificationChannel on which created notifications are posted on.

DEFAULT_NOTIFICATION_ID

public static final int DEFAULT_NOTIFICATION_ID = 1001

The default ID used for the notificationId.

GROUP_KEY

public static final String GROUP_KEY = "media3_group_key"

The group key used for the setGroup to avoid the media notification being auto-grouped with the other notifications. The other notifications sent from the app shouldn't use this group key.

Public constructors

DefaultMediaNotificationProvider

public DefaultMediaNotificationProvider(Context context)

Creates an instance. Use this constructor only when you want to override methods of this class. Otherwise use Builder.

DefaultMediaNotificationProvider

public DefaultMediaNotificationProvider(
    Context context,
    DefaultMediaNotificationProvider.NotificationIdProvider notificationIdProvider,
    String channelId,
    int channelNameResourceId
)

Creates an instance. Use this constructor only when you want to override methods of this class. Otherwise use Builder.

Public methods

createNotification

public final MediaNotification createNotification(
    MediaSession mediaSession,
    ImmutableList<CommandButton> customLayout,
    MediaNotification.ActionFactory actionFactory,
    MediaNotification.Provider.Callback onNotificationChangedCallback
)

Creates a new MediaNotification.

Parameters
MediaSession mediaSession

The media session.
ImmutableList<CommandButton> customLayout

The custom layout set by the session.
MediaNotification.ActionFactory actionFactory

The ActionFactory for creating notification actions.
MediaNotification.Provider.Callback onNotificationChangedCallback

A callback that the provider needs to notify when the notification has changed and needs to be posted again, for example after a bitmap has been loaded asynchronously.

handleCustomCommand

public final boolean handleCustomCommand(MediaSession session, String action, Bundle extras)

Handles a notification's custom command.

Parameters
MediaSession session

The media session.
String action

The custom command action.
Bundle extras

A bundle set in the custom command, otherwise EMPTY.
Returns
boolean

false if the action should be delivered to the session as a custom command or true if the action has been handled completely by the provider.
See also
createCustomAction

setSmallIcon

public final void setSmallIcon(@DrawableRes int smallIconResourceId)

Sets the small icon of the notification which is also shown in the system status bar.

Parameters
@DrawableRes int smallIconResourceId

The resource id of the small icon.
See also
setSmallIcon

Protected methods

addNotificationActions

protected int[] addNotificationActions(
    MediaSession mediaSession,
    ImmutableList<CommandButton> mediaButtons,
    NotificationCompat.Builder builder,
    MediaNotification.ActionFactory actionFactory
)

Adds the media buttons to the notification builder for the given action factory.

The list of mediaButtons is the list resulting from getMediaButtons.

Override this method to customize how the media buttons are added to the notification and define which actions are shown in compact view by returning the indices of the buttons to be shown in compact view.

By default, the buttons for seekToPreviousMediaItem, play or pause, seekToNextMediaItem are shown in compact view, unless some of the buttons are marked with COMMAND_KEY_COMPACT_VIEW_INDEX to declare the index in compact view of the given command button in the button extras.

Parameters
MediaSession mediaSession

The media session to which the actions will be sent.
ImmutableList<CommandButton> mediaButtons

The command buttons to be included in the notification.
NotificationCompat.Builder builder

The builder to add the actions to.
MediaNotification.ActionFactory actionFactory

The actions factory to be used to build notifications.
Returns
int[]

The indices of the buttons to be used in compact view of the notification.

getMediaButtons

protected ImmutableList<CommandButton> getMediaButtons(
    MediaSession session,
    Player.Commands playerCommands,
    ImmutableList<CommandButton> customLayout,
    boolean showPauseButton
)

Returns the ordered list of command buttons to be used to build the notification.

This method is called each time a new notification is built.

Override this method to customize the buttons on the notification. Commands of the buttons returned by this method must be contained in getAvailableCommands.

By default, the notification shows buttons for seekToPreviousMediaItem, play or pause, seekToNextMediaItem in compact view. This can be customized by defining the index of the command in compact view of up to 3 commands in their extras with key COMMAND_KEY_COMPACT_VIEW_INDEX.

To make the custom layout and commands work, you need to set the custom layout of commands and add the custom commands to the available commands when a controller connects to the session. Controllers that connect after you called setCustomLayout need the custom command set in onPostConnect also.

Parameters
MediaSession session

The media session.
Player.Commands playerCommands

The available player commands.
ImmutableList<CommandButton> customLayout

The custom layout of commands.
boolean showPauseButton

Whether the notification should show a pause button (e.g., because the player is currently playing content), otherwise show a play button to start playback.
Returns
ImmutableList<CommandButton>

The ordered list of command buttons to be placed on the notification.

getNotificationContentText

protected @Nullable CharSequence getNotificationContentText(MediaMetadata metadata)

Returns the content text to be used to build the notification.

This method is called each time a new notification is built.

Override this method to customize which field of MediaMetadata is used for content text of the notification.

By default, the notification shows artist as content text.

Parameters
MediaMetadata metadata

The media metadata from which content text is fetched.
Returns
@Nullable CharSequence

Notification content text.

getNotificationContentTitle

protected @Nullable CharSequence getNotificationContentTitle(MediaMetadata metadata)

Returns the content title to be used to build the notification.

This method is called each time a new notification is built.

Override this method to customize which field of MediaMetadata is used for content title of the notification.

By default, the notification shows title as content title.

Parameters
MediaMetadata metadata

The media metadata from which content title is fetched.
Returns
@Nullable CharSequence

Notification content title.