Skip to content

Plugin: Media Session

MediaSessionPlugin (id 'media-session') bridges player transport state to the browser’s navigator.mediaSession API, lock-screen media controls, hardware media keys, Bluetooth remotes, and OS “Now Playing” widgets. Not re-exported from the main entry, import it from the plugins/media-session subpath.

Options

Currently empty (MediaSessionOptions = {}), reserved for future options.

Rules & restrictions

  • Silently no-ops entirely when navigator.mediaSession is absent (Node, JSDOM, some older WebViews), every method is guarded at the top, nothing throws.
  • Position reporting is skipped when duration is zero, NaN, or Infinity, some browsers throw on an invalid setPositionState call.
  • setActionHandler('stop') isn’t supported in every browser, the resulting TypeError is caught rather than propagated.
  • Safari specifically requires the autoplay attribute on the host <iframe> (when embedded) for MediaSession to activate at all, see the note on the Embed plugin.

How to extend it

To target a native shell (Capacitor, Electron) instead of the browser API, subclass with the same static id and override the platform touchpoints:

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player'; // nomercy-music-player's factory works identically
import { MediaSessionPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/media-session';

const player = nmplayer('player');

player.addPlugin(MediaSessionPlugin);
await player.ready();

const session = player.getPlugin(MediaSessionPlugin);
session!.metadata({ title: 'Sintel', artist: 'Blender Foundation' });

Next steps

  • Plugin: Message: the in-player toast surface, for feedback the OS chrome doesn’t cover.