PlayerNotificationManager

@UnstableApi
class PlayerNotificationManager

Starts, updates and cancels a media style notification reflecting the player state. The actions included in the notification can be customized along with their drawables, as described below.

The notification is cancelled when null is passed to setPlayer or when the notification is dismissed by the user.

If the player is released it must be removed from the manager by calling setPlayer(null).

Action customization

Playback actions can be included or omitted as follows:
  • usePlayPauseActions - Sets whether the play and pause actions are used.
  • useRewindAction - Sets whether the rewind action is used.
  • useRewindActionInCompactView - If useRewindAction is true, sets whether the rewind action is also used in compact view (including the lock screen notification). Else does nothing.
  • useFastForwardAction - Sets whether the fast forward action is used.
  • useFastForwardActionInCompactView - If useFastForwardAction is true, sets whether the fast forward action is also used in compact view (including the lock screen notification). Else does nothing.
  • usePreviousAction - Whether the previous action is used.
  • usePreviousActionInCompactView - If usePreviousAction is true, sets whether the previous action is also used in compact view (including the lock screen notification). Else does nothing.
  • useNextAction - Whether the next action is used.
  • useNextActionInCompactView - If useNextAction is true, sets whether the next action is also used in compact view (including the lock screen notification). Else does nothing.
  • useStopAction - Sets whether the stop action is used.

Overriding drawables

The drawables used by PlayerNotificationManager can be overridden by drawables with the same names defined in your application. The drawables that can be overridden are:
  • exo_notification_small_icon - The icon passed by default to setSmallIcon. A different icon can also be specified programmatically by calling setSmallIcon.
  • exo_notification_play - The play icon.
  • exo_notification_pause - The pause icon.
  • exo_notification_rewind - The rewind icon.
  • exo_notification_fastforward - The fast forward icon.
  • exo_notification_previous - The previous icon.
  • exo_notification_next - The next icon.
  • exo_notification_stop - The stop icon.

Alternatively, the action icons can be set programmatically by using the Builder.

Unlike the drawables above, the large icon (i.e. the icon passed to setLargeIcon cannot be overridden in this way. Instead, the large icon is obtained from the MediaDescriptionAdapter passed to Builder.

Note: This class would require POST_NOTIFICATIONS permission if used without a media session.

Summary

Nested types

Receives a Bitmap.

A builder for PlayerNotificationManager instances.

Defines and handles custom actions.

An adapter to provide content assets of the media currently playing.

A listener for changes to the notification.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = [NotificationCompat.PRIORITY_DEFAULT, NotificationCompat.PRIORITY_MAX, NotificationCompat.PRIORITY_HIGH, NotificationCompat.PRIORITY_LOW, NotificationCompat.PRIORITY_MIN])
annotation PlayerNotificationManager.Priority

Priority of the notification (required for API 25 and lower).
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = [NotificationCompat.VISIBILITY_PRIVATE, NotificationCompat.VISIBILITY_PUBLIC, NotificationCompat.VISIBILITY_SECRET])
annotation PlayerNotificationManager.Visibility

Visibility of notification on the lock screen.

Constants
const String!
ACTION_FAST_FORWARD = "androidx.media3.ui.notification.ffwd"

The action which fast forwards.
const String!
ACTION_NEXT = "androidx.media3.ui.notification.next"

The action which skips to the next media item.
const String!
ACTION_PAUSE = "androidx.media3.ui.notification.pause"

The action which pauses playback.
const String!
ACTION_PLAY = "androidx.media3.ui.notification.play"

The action which starts playback.
const String!
ACTION_PREVIOUS = "androidx.media3.ui.notification.prev"

The action which skips to the previous media item.
const String!
ACTION_REWIND = "androidx.media3.ui.notification.rewind"

The action which rewinds.
const String!
ACTION_STOP = "androidx.media3.ui.notification.stop"

The action which stops playback.
const String!
EXTRA_INSTANCE_ID = "INSTANCE_ID"

The extra key of the instance id of the player notification manager.

Protected constructors
PlayerNotificationManager(
    context: Context!,
    channelId: String!,
    notificationId: Int,
    mediaDescriptionAdapter: PlayerNotificationManager.MediaDescriptionAdapter!,
    notificationListener: PlayerNotificationManager.NotificationListener?,
    customActionReceiver: PlayerNotificationManager.CustomActionReceiver?,
    smallIconResourceId: Int,
    playActionIconResourceId: Int,
    pauseActionIconResourceId: Int,
    stopActionIconResourceId: Int,
    rewindActionIconResourceId: Int,
    fastForwardActionIconResourceId: Int,
    previousActionIconResourceId: Int,
    nextActionIconResourceId: Int,
    groupKey: String?
)

Public functions
Unit

Forces an update of the notification if already started.
Unit
setBadgeIconType(badgeIconType: Int)

Sets the badge icon type of the notification.
Unit
setColor(color: Int)

Sets the accent color of the notification.
Unit
setColorized(colorized: Boolean)

Sets whether the notification should be colorized.
Unit
setDefaults(defaults: Int)

Sets the defaults.
Unit

This function is deprecated.

Use setMediaSessionToken and pass in (MediaSession.Token) compatToken.getToken().
Unit

Sets the MediaSession.Token.
Unit
setPlayer(player: Player?)

Sets the Player.
Unit

Sets the priority of the notification required for API 25 and lower.
Unit
setShowPlayButtonIfPlaybackIsSuppressed(
    showPlayButtonIfSuppressed: Boolean
)

Sets whether a play button is shown if playback is suppressed.
Unit
setSmallIcon(smallIconResourceId: @DrawableRes Int)

Sets the small icon of the notification which is also shown in the system status bar.
Unit
setUseChronometer(useChronometer: Boolean)

Sets whether the elapsed time of the media playback should be displayed.
Unit
setUseFastForwardAction(useFastForwardAction: Boolean)

Sets whether the fast forward action should be used.
Unit
setUseFastForwardActionInCompactView(
    useFastForwardActionInCompactView: Boolean
)

Sets whether the fast forward action should also be used in compact view.
Unit
setUseNextAction(useNextAction: Boolean)

Sets whether the next action should be used.
Unit
setUseNextActionInCompactView(useNextActionInCompactView: Boolean)

If useNextAction is true, sets whether the next action should also be used in compact view.
Unit
setUsePlayPauseActions(usePlayPauseActions: Boolean)

Sets whether the play and pause actions should be used.
Unit
setUsePreviousAction(usePreviousAction: Boolean)

Sets whether the previous action should be used.
Unit
setUsePreviousActionInCompactView(
    usePreviousActionInCompactView: Boolean
)

If usePreviousAction is true, sets whether the previous action should also be used in compact view.
Unit
setUseRewindAction(useRewindAction: Boolean)

Sets whether the rewind action should be used.
Unit
setUseRewindActionInCompactView(useRewindActionInCompactView: Boolean)

Sets whether the rewind action should also be used in compact view.
Unit
setUseStopAction(useStopAction: Boolean)

Sets whether the stop action should be used.
Unit

Sets the visibility of the notification which determines whether and how the notification is shown when the device is in lock screen mode.

Protected functions
NotificationCompat.Builder?
createNotification(
    player: Player!,
    builder: NotificationCompat.Builder?,
    ongoing: Boolean,
    largeIcon: Bitmap?
)

Creates the notification given the current player state.
IntArray<Int>!
getActionIndicesForCompactView(
    actionNames: (Mutable)List<String!>!,
    player: Player!
)

Gets an array with the indices of the buttons to be shown in compact mode.
(Mutable)List<String!>!
getActions(player: Player!)

Gets the names and order of the actions to be included in the notification at the current player state.
Boolean
getOngoing(player: Player!)

Returns whether the generated notification should be ongoing.

Constants

ACTION_FAST_FORWARD

const val ACTION_FAST_FORWARD = "androidx.media3.ui.notification.ffwd": String!

The action which fast forwards.

ACTION_NEXT

const val ACTION_NEXT = "androidx.media3.ui.notification.next": String!

The action which skips to the next media item.

ACTION_PAUSE

const val ACTION_PAUSE = "androidx.media3.ui.notification.pause": String!

The action which pauses playback.

ACTION_PLAY

const val ACTION_PLAY = "androidx.media3.ui.notification.play": String!

The action which starts playback.

ACTION_PREVIOUS

const val ACTION_PREVIOUS = "androidx.media3.ui.notification.prev": String!

The action which skips to the previous media item.

ACTION_REWIND

const val ACTION_REWIND = "androidx.media3.ui.notification.rewind": String!

The action which rewinds.

ACTION_STOP

const val ACTION_STOP = "androidx.media3.ui.notification.stop": String!

The action which stops playback.

EXTRA_INSTANCE_ID

const val EXTRA_INSTANCE_ID = "INSTANCE_ID": String!

The extra key of the instance id of the player notification manager.

Protected constructors

PlayerNotificationManager

protected PlayerNotificationManager(
    context: Context!,
    channelId: String!,
    notificationId: Int,
    mediaDescriptionAdapter: PlayerNotificationManager.MediaDescriptionAdapter!,
    notificationListener: PlayerNotificationManager.NotificationListener?,
    customActionReceiver: PlayerNotificationManager.CustomActionReceiver?,
    smallIconResourceId: Int,
    playActionIconResourceId: Int,
    pauseActionIconResourceId: Int,
    stopActionIconResourceId: Int,
    rewindActionIconResourceId: Int,
    fastForwardActionIconResourceId: Int,
    previousActionIconResourceId: Int,
    nextActionIconResourceId: Int,
    groupKey: String?
)

Public functions

invalidate

fun invalidate(): Unit

Forces an update of the notification if already started.

setBadgeIconType

fun setBadgeIconType(badgeIconType: Int): Unit

Sets the badge icon type of the notification.

See setBadgeIconType.

Parameters
badgeIconType: Int

The badge icon type.

setColor

fun setColor(color: Int): Unit

Sets the accent color of the notification.

See setColor.

Parameters
color: Int

The color, in ARGB integer form like the constants in Color.

setColorized

fun setColorized(colorized: Boolean): Unit

Sets whether the notification should be colorized. When set, the color set with setColor will be used as the background color for the notification.

See setColorized.

Parameters
colorized: Boolean

Whether to colorize the notification.

setDefaults

fun setDefaults(defaults: Int): Unit

Sets the defaults.

See setDefaults.

Parameters
defaults: Int

The default notification options.

setMediaSessionToken

fun setMediaSessionToken(compatToken: MediaSessionCompat.Token!): Unit

setMediaSessionToken

fun setMediaSessionToken(token: MediaSession.Token!): Unit

Sets the MediaSession.Token.

When using MediaSessionCompat, this token can be obtained with (MediaSession.Token) compatToken.getToken().

Parameters
token: MediaSession.Token!

The MediaSession.Token.

setPlayer

fun setPlayer(player: Player?): Unit

Sets the Player.

Setting the player starts a notification immediately unless the player is in STATE_IDLE, in which case the notification is started as soon as the player transitions away from being idle.

If the player is released it must be removed from the manager by calling setPlayer(null). This will cancel the notification.

Parameters
player: Player?

The Player to use, or null to remove the current player. Only players which are accessed on the main thread are supported ( player.getApplicationLooper() == Looper.getMainLooper()).

setPriority

fun setPriority(@PlayerNotificationManager.Priority priority: Int): Unit

Sets the priority of the notification required for API 25 and lower.

See setPriority.

To set the priority for API levels above 25, you can create your own with a given importance level and pass the id of the channel to Builder.

Parameters
@PlayerNotificationManager.Priority priority: Int

The priority which can be one of PRIORITY_DEFAULT, PRIORITY_MAX, PRIORITY_HIGH, PRIORITY_LOW or PRIORITY_MIN. If not set PRIORITY_LOW is used by default.

setShowPlayButtonIfPlaybackIsSuppressed

fun setShowPlayButtonIfPlaybackIsSuppressed(
    showPlayButtonIfSuppressed: Boolean
): Unit

Sets whether a play button is shown if playback is suppressed.

The default is true.

Parameters
showPlayButtonIfSuppressed: Boolean

Whether to show a play button if playback is suppressed.

setSmallIcon

fun setSmallIcon(smallIconResourceId: @DrawableRes Int): Unit

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

See setSmallIcon.

Parameters
smallIconResourceId: @DrawableRes Int

The resource id of the small icon.

setUseChronometer

fun setUseChronometer(useChronometer: Boolean): Unit

Sets whether the elapsed time of the media playback should be displayed.

Note that this setting only works if all of the following are true:

See setUsesChronometer.

Parameters
useChronometer: Boolean

Whether to use chronometer.

setUseFastForwardAction

fun setUseFastForwardAction(useFastForwardAction: Boolean): Unit

Sets whether the fast forward action should be used.

Parameters
useFastForwardAction: Boolean

Whether to use the fast forward action.

setUseFastForwardActionInCompactView

fun setUseFastForwardActionInCompactView(
    useFastForwardActionInCompactView: Boolean
): Unit

Sets whether the fast forward action should also be used in compact view. Has no effect if ACTION_FAST_FORWARD is not enabled, for instance if the media is not seekable.

If set to true, setUseNextActionInCompactView is set to false.

Parameters
useFastForwardActionInCompactView: Boolean

Whether to use the fast forward action in compact view.

setUseNextAction

fun setUseNextAction(useNextAction: Boolean): Unit

Sets whether the next action should be used.

Parameters
useNextAction: Boolean

Whether to use the next action.

setUseNextActionInCompactView

fun setUseNextActionInCompactView(useNextActionInCompactView: Boolean): Unit

If useNextAction is true, sets whether the next action should also be used in compact view. Has no effect if useNextAction is false.

If set to true, setUseFastForwardActionInCompactView is set to false.

Parameters
useNextActionInCompactView: Boolean

Whether to use the next action in compact view.

setUsePlayPauseActions

fun setUsePlayPauseActions(usePlayPauseActions: Boolean): Unit

Sets whether the play and pause actions should be used.

Parameters
usePlayPauseActions: Boolean

Whether to use play and pause actions.

setUsePreviousAction

fun setUsePreviousAction(usePreviousAction: Boolean): Unit

Sets whether the previous action should be used.

Parameters
usePreviousAction: Boolean

Whether to use the previous action.

setUsePreviousActionInCompactView

fun setUsePreviousActionInCompactView(
    usePreviousActionInCompactView: Boolean
): Unit

If usePreviousAction is true, sets whether the previous action should also be used in compact view. Has no effect if usePreviousAction is false.

If set to true, setUseRewindActionInCompactView is set to false.

Parameters
usePreviousActionInCompactView: Boolean

Whether to use the previous action in compact view.

setUseRewindAction

fun setUseRewindAction(useRewindAction: Boolean): Unit

Sets whether the rewind action should be used.

Parameters
useRewindAction: Boolean

Whether to use the rewind action.

setUseRewindActionInCompactView

fun setUseRewindActionInCompactView(useRewindActionInCompactView: Boolean): Unit

Sets whether the rewind action should also be used in compact view. Has no effect if ACTION_REWIND is not enabled, for instance if the media is not seekable.

If set to true, setUsePreviousActionInCompactView is set to false.

Parameters
useRewindActionInCompactView: Boolean

Whether to use the rewind action in compact view.

setUseStopAction

fun setUseStopAction(useStopAction: Boolean): Unit

Sets whether the stop action should be used.

Parameters
useStopAction: Boolean

Whether to use the stop action.

setVisibility

fun setVisibility(@PlayerNotificationManager.Visibility visibility: Int): Unit

Sets the visibility of the notification which determines whether and how the notification is shown when the device is in lock screen mode.

See setVisibility.

Parameters
@PlayerNotificationManager.Visibility visibility: Int

The visibility which must be one of VISIBILITY_PUBLIC, VISIBILITY_PRIVATE or VISIBILITY_SECRET.

Protected functions

createNotification

protected fun createNotification(
    player: Player!,
    builder: NotificationCompat.Builder?,
    ongoing: Boolean,
    largeIcon: Bitmap?
): NotificationCompat.Builder?

Creates the notification given the current player state.

Parameters
player: Player!

The player for which state to build a notification.
builder: NotificationCompat.Builder?

The builder used to build the last notification, or null.
ongoing: Boolean

Whether the notification should be ongoing.
largeIcon: Bitmap?

The large icon to be used.
Returns
NotificationCompat.Builder?

The NotificationCompat.Builder on which to call build to obtain the notification, or null if no notification should be displayed.

getActionIndicesForCompactView

protected fun getActionIndicesForCompactView(
    actionNames: (Mutable)List<String!>!,
    player: Player!
): IntArray<Int>!

Gets an array with the indices of the buttons to be shown in compact mode.

This method can be overridden. The indices must refer to the list of actions passed as the first parameter.

Parameters
actionNames: (Mutable)List<String!>!

The names of the actions included in the notification.
player: Player!

The player for which a notification is being built.

getActions

protected fun getActions(player: Player!): (Mutable)List<String!>!

Gets the names and order of the actions to be included in the notification at the current player state.

The playback and custom actions are combined and placed in the following order if not omitted: 

  +------------------------------------------------------------------------+
  | prev | << | play/pause | >> | next | custom actions | stop |
  +------------------------------------------------------------------------+

This method can be safely overridden. However, the names must be of the playback actions ACTION_PAUSE, ACTION_PLAY, ACTION_FAST_FORWARD, ACTION_REWIND, ACTION_NEXT or ACTION_PREVIOUS, or a key contained in the map returned by createCustomActions. Otherwise the action name is ignored.

getOngoing

protected fun getOngoing(player: Player!): Boolean

Returns whether the generated notification should be ongoing.