MediaSessionPlugin

When music is playing, the operating system can show the track title, artist, album, and artwork on the lock screen and in the notification panel, and let the user skip or pause from hardware media keys or Bluetooth remotes. Without this plugin, none of that happens. Register MediaSessionPlugin and the browser’s Media Session API wires itself to your player automatically.

The music-specific subclass reads name, artist, album, and cover from each MusicPlaylistItem. The base player core plugin handles all transport state: play, pause, stop, seek, and position scrubbing.

import { MediaSessionPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

Plugin id: 'media-session'

Artwork resolution

Artwork is not configured on this plugin. The player core base class reads the first non-empty value from item.image, item.poster, item.thumbnail, or item.cover, then resolves it through the player’s urlResolver pipeline. To control how image URLs are rewritten, pass baseUrl or a custom urlResolver to setup().

What it does

The plugin registers these behaviors on use():

• current event - calls getMetadata(item) and pushes the result to navigator.mediaSession.metadata.
• play / pause / ended events - updates navigator.mediaSession.playbackState ('playing', 'paused', 'none').
• time and seek events - calls setPositionState so the lock-screen scrubber tracks the current position.
• OS action handlers: play, pause, stop, previoustrack, nexttrack, seekbackward, seekforward, seekto.

If the current item is already set when the plugin’s use() runs, the OS metadata seeds immediately without waiting for the next track change.

In environments without navigator.mediaSession (Node, JSDOM, older WebViews) the plugin silently no-ops.

Field mapping

The music subclass maps MusicPlaylistItem fields to MediaMetadata:

Methods

import { MediaSessionPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const session = player.getPlugin(MediaSessionPlugin)!;

// Read the last metadata that was pushed to the OS:
const currentMeta = session.metadata();

// Manually push metadata (overrides the automatic update):
session.metadata({
  title: 'Custom Title',
  artist: 'Custom Artist',
});

// Clear the OS Now Playing / lock-screen display:
session.clearMetadata();

Registration

import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { MediaSessionPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(MediaSessionPlugin)
  .setup({
    baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music',
    playlist: [
      {
        id: 'kjc-01',
        name: 'Thaw You Out',
        url: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.mp3',
        cover: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.jpg',
        artist: 'Derek Clegg',
        album: 'KJC',
      },
    ],
  });

On track change the OS lock screen and notification panel show the title, artist, album, and artwork resolved from cover.

Browser support

The Media Session API is supported in Chrome, Firefox, and Safari. In environments where it is unavailable the plugin silently no-ops without throwing. Safari requires the autoplay attribute on the <iframe> when the player is embedded. Without it OS-level controls do not appear.

See also

• MusicPlaylistItem, name, artist, album, cover fields
• Quick Start, minimal player with MediaSessionPlugin