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:

• Notification controls appear only when an active AudioContext is running.
• show() and hide() only update metadata; they do not control notification visibility.
• The notification appears and disappears automatically based on the audio session state.
• Creating and resuming an AudioContext shows the controls.
• Suspending or closing the AudioContext hides the controls.

Android:

• Notification visibility is controlled directly by show() and hide().
• Notification controls work independently of AudioContext state.

Example

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

// 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 skipForwardListener = PlaybackNotificationManager.addEventListener(
  'playbackNotificationSkipForward',
  (event) => {
    seekBy(event.value);
  }
);

const skipBackwardListener = PlaybackNotificationManager.addEventListener(
  'playbackNotificationSkipBackward',
  (event) => {
    seekBy(-event.value);
  }
);

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();
skipForwardListener.remove();
skipBackwardListener.remove();
seekToListener.remove();
PlaybackNotificationManager.hide();

Methods

show

Displays 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

Hides 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

Enables or disables 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

Checks if the notification is currently active and visible.

Returns Promise<boolean>.

addEventListener

Adds an event listener for notification actions.

Parameter	Type	Description
eventName	PlaybackNotificationEventName	The event to listen for
callback	NotificationCallback	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';

  skipInterval?: number;

  // IOS only: shows the system "Live" indicator on the lock screen and CarPlay Now Playing UI
  isLiveStream?: boolean;
}

skipInterval

• Configures how many seconds playbackNotificationSkipForward and playbackNotificationSkipBackward advance or rewind.
• Defaults to 15 when omitted.
• Clamped to 1–120 seconds in JavaScript before being passed to native.
• Pass skipInterval in the same show() call (or earlier) before enabling skip controls, so the interval is applied when controls are first set up.
• On Android, skip action icons show 15 when skipInterval is 15 (default); otherwise generic skip icons without a number are used.

isLiveStream

• Marks the current item as a live stream (e.g. live radio) rather than a track with a known duration.
• iOS only: maps to MPNowPlayingInfoPropertyIsLiveStream, which drives the "Live" label shown on the lock screen and CarPlay Now Playing UI.
• No effect on Android — there is no equivalent system-level indicator to map it to.

PlaybackControlName

Type definitions

type PlaybackControlName =
  | 'play'
  | 'pause'
  | 'stop'
  | 'nextTrack'
  | 'previousTrack'
  | 'skipForward'
  | 'skipBackward'
  | 'seekTo';

PlaybackNotificationEventName

Type definitions

interface EventEmptyType {}

interface EventTypeWithValue {
  value: number;
}

interface PlaybackNotificationEvent {
  playbackNotificationPlay: EventEmptyType;
  playbackNotificationPause: EventEmptyType;
  playbackNotificationStop: EventEmptyType;
  playbackNotificationNextTrack: EventEmptyType;
  playbackNotificationPreviousTrack: EventEmptyType;
  playbackNotificationSkipForward: EventTypeWithValue;
  playbackNotificationSkipBackward: EventTypeWithValue;
  playbackNotificationSeekTo: EventTypeWithValue;
  playbackNotificationDismissed: EventEmptyType;
}

type PlaybackNotificationEventName = keyof PlaybackNotificationEvent;

NotificationCallback

Type definitions

type NotificationCallback<Name extends PlaybackNotificationEventName> = (
  event: PlaybackNotificationEvent[Name]
) => void;