DefaultMediaNotificationProvider

@UnstableApi
class DefaultMediaNotificationProvider : 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_icon_play - The play icon.
  • media3_icon_pause - The pause icon.
  • media3_icon_previous - The previous icon.
  • media3_icon_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
const 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.
const String!
DEFAULT_CHANNEL_ID = "default_channel_id"

The default ID used for the NotificationChannel on which created notifications are posted on.
const @StringRes Int

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

The default ID used for the notificationId.
const 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!,
    notificationIdProvider: DefaultMediaNotificationProvider.NotificationIdProvider!,
    channelId: String!,
    channelNameResourceId: Int
)

Creates an instance.

Public functions
MediaNotification!
createNotification(
    mediaSession: MediaSession!,
    mediaButtonPreferences: ImmutableList<CommandButton!>!,
    actionFactory: MediaNotification.ActionFactory!,
    onNotificationChangedCallback: MediaNotification.Provider.Callback!
)

Creates a new MediaNotification.
Boolean
handleCustomCommand(session: MediaSession!, action: String!, extras: Bundle!)

Handles a notification's custom command.
Unit
setSmallIcon(smallIconResourceId: @DrawableRes Int)

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

Protected functions
IntArray<Int>!
addNotificationActions(
    mediaSession: MediaSession!,
    mediaButtons: ImmutableList<CommandButton!>!,
    builder: NotificationCompat.Builder!,
    actionFactory: MediaNotification.ActionFactory!
)

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

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

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

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

Constants

COMMAND_KEY_COMPACT_VIEW_INDEX

const val COMMAND_KEY_COMPACT_VIEW_INDEX = "androidx.media3.session.command.COMPACT_VIEW_INDEX": String!

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

DEFAULT_CHANNEL_ID

const val DEFAULT_CHANNEL_ID = "default_channel_id": String!

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

DEFAULT_CHANNEL_NAME_RESOURCE_ID

const val DEFAULT_CHANNEL_NAME_RESOURCE_ID: @StringRes Int

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

DEFAULT_NOTIFICATION_ID

const val DEFAULT_NOTIFICATION_ID = 1001: Int

The default ID used for the notificationId.

GROUP_KEY

const val GROUP_KEY = "media3_group_key": String!

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

DefaultMediaNotificationProvider(context: Context!)

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

DefaultMediaNotificationProvider

DefaultMediaNotificationProvider(
    context: Context!,
    notificationIdProvider: DefaultMediaNotificationProvider.NotificationIdProvider!,
    channelId: String!,
    channelNameResourceId: Int
)

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

Public functions

createNotification

fun createNotification(
    mediaSession: MediaSession!,
    mediaButtonPreferences: ImmutableList<CommandButton!>!,
    actionFactory: MediaNotification.ActionFactory!,
    onNotificationChangedCallback: MediaNotification.Provider.Callback!
): MediaNotification!

Creates a new MediaNotification.

Parameters
mediaSession: MediaSession!

The media session.
mediaButtonPreferences: ImmutableList<CommandButton!>!

The media button preferences set by the session.
actionFactory: MediaNotification.ActionFactory!

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

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

fun handleCustomCommand(session: MediaSession!, action: String!, extras: Bundle!): Boolean

Handles a notification's custom command.

Parameters
session: MediaSession!

The media session.
action: String!

The custom command action.
extras: Bundle!

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

fun setSmallIcon(smallIconResourceId: @DrawableRes Int): Unit

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

Parameters
smallIconResourceId: @DrawableRes Int

The resource id of the small icon.
See also
setSmallIcon

Protected functions

addNotificationActions

protected fun addNotificationActions(
    mediaSession: MediaSession!,
    mediaButtons: ImmutableList<CommandButton!>!,
    builder: NotificationCompat.Builder!,
    actionFactory: MediaNotification.ActionFactory!
): IntArray<Int>!

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.
mediaButtons: ImmutableList<CommandButton!>!

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

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

The actions factory to be used to build notifications.
Returns
IntArray<Int>!

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

getMediaButtons

protected fun getMediaButtons(
    session: MediaSession!,
    playerCommands: Player.Commands!,
    mediaButtonPreferences: ImmutableList<CommandButton!>!,
    showPauseButton: Boolean
): ImmutableList<CommandButton!>!

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 media button preferences and custom commands work, you need to set the media button preferences and add the custom commands to the available commands when a controller connects to the session. Controllers that connect after you called setMediaButtonPreferences need the custom command set in onPostConnect too.

Parameters
session: MediaSession!

The media session.
playerCommands: Player.Commands!

The available player commands.
mediaButtonPreferences: ImmutableList<CommandButton!>!

The media button preferences.
showPauseButton: Boolean

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 fun getNotificationContentText(metadata: MediaMetadata!): CharSequence?

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
metadata: MediaMetadata!

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

Notification content text.

getNotificationContentTitle

protected fun getNotificationContentTitle(metadata: MediaMetadata!): CharSequence?

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
metadata: MediaMetadata!

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

Notification content title.