PlaybackNotificationManager

The PlaybackNotificationManager provides media session integration and playback controls for your audio application. It manages system-level media notifications with controls like play, pause, next, previous, and seek functionality.

Platform Differences

iOS Requirements:

• Notification controls only appear when an active AudioContext is running
• show() or hide() only update metadata - they don't control notification visibility
• The notification automatically appears/disappears based on audio session state
• To show: create and resume an AudioContext
• To hide: suspend or close the AudioContext

Android:

• Notification visibility is directly controlled by show() and hide() methods
• Works independently of AudioContext state

Example

// show notification
await PlaybackNotificationManager.show({
  title: 'My Song',
  artist: 'My Artist',
  duration: 180,
  state: 'paused',
});

// Listen for notification controls
const playListener = PlaybackNotificationManager.addEventListener(
  'playbackNotificationPlay',
  () => {
    // Handle play action
    PlaybackNotificationManager.show({ state: 'playing' });
  }
);

const pauseListener = PlaybackNotificationManager.addEventListener(
  'playbackNotificationPause',
  () => {
    // Handle pause action
    PlaybackNotificationManager.show({ state: 'paused' });
  }
);

const seekToListener = PlaybackNotificationManager.addEventListener(
  'playbackNotificationSeekTo',
  (event) => {
    // Handle seek to position (event.value is in seconds)
    PlaybackNotificationManager.show({ elapsedTime: event.value });
  }
);

// Update progress
PlaybackNotificationManager.show({ elapsedTime: 60 });

// Cleanup
playListener.remove();
pauseListener.remove();
seekToListener.remove();
PlaybackNotificationManager.hide();

Methods

show

Display the notification with initial metadata.

iOS Behavior

On iOS, this method only sets the metadata. The notification controls will only appear when an AudioContext is actively running. Make sure to create and resume an AudioContext before calling show().

info

Metadata is remembered between calls, so after initial passing the metadata to show function, you can only call it with elements that are supposed to change.

Parameter	Type	Description
info	PlaybackNotificationInfo	Initial notification metadata

Returns Promise<void>.

hide

Hide the notification. Can be shown again later by calling show().

iOS Behavior

On iOS, this method clears the metadata but does not hide the notification controls. To completely hide controls on iOS, you must suspend or close the AudioContext.

Returns Promise<void>.

enableControl

Enable or disable specific playback controls.

Parameter	Type	Description
control	PlaybackControlName	The control to enable/disable
enabled	boolean	Whether the control should be enabled

Returns Promise<void>.

isActive

Check if the notification is currently active and visible.

Returns Promise<boolean>.

addEventListener

Add an event listener for notification actions.

Parameter	Type	Description
eventName	PlaybackNotificationEventName	The event to listen for
callback	SystemEventCallback	Callback function

Returns AudioEventSubscription.

Remarks

PlaybackNotificationInfo

Type definitions

interface PlaybackNotificationInfo {
  title?: string;
  artist?: string;
  album?: string;

  // Can be a URL or a local file path relative to drawable resources (Android) or bundle resources (iOS)
  artwork?: string | { uri: string };
  // ANDROID: small icon shown in the status bar
  androidSmallIcon?: string | { uri: string };
  duration?: number;

  // IOS: elapsed time does not update automatically, must be set manually on each state change
  elapsedTime?: number;
  speed?: number;
  state?: 'playing' | 'paused';
}

PlaybackControlName

Type definitions

type PlaybackControlName =
  | 'play'
  | 'pause'
  | 'next'
  | 'previous'
  | 'skipForward'
  | 'skipBackward'
  | 'seekTo';

PlaybackNotificationEventName

Type definitions

interface EventTypeWithValue {
  value: number;
}

interface PlaybackNotificationEvent {
  playbackNotificationPlay: EventEmptyType;
  playbackNotificationPause: EventEmptyType;
  playbackNotificationNext: EventEmptyType;
  playbackNotificationPrevious: EventEmptyType;
  playbackNotificationSkipForward: EventTypeWithValue;
  playbackNotificationSkipBackward: EventTypeWithValue;
  playbackNotificationSeekTo: EventTypeWithValue;
  playbackNotificationDismissed: EventEmptyType;
}

type PlaybackNotificationEventName = keyof PlaybackNotificationEvent;