Skip to content

MessagePlugin

You need a way to tell the listener what’s happening without building a full notification system. MessagePlugin gives you a toast surface in the player container that any plugin or consumer can write to. Call show('text') and it appears, stays for a moment, then disappears on its own. For blocking states like an autoplay-blocked “Tap to play” prompt, use displayPersistent() instead, and it stays until you explicitly remove it.

This plugin is a direct re-export of the player core’s MessagePlugin. There are no music-specific overrides.

TypeScript
import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { MessagePlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';
import type { MessageOptions } from '@nomercy-entertainment/nomercy-music-player/plugins';

Plugin id: 'message'

Options

OptionTypeDefaultDescription
durationMsnumber3000Default display duration in milliseconds for transient messages. Applies in displayMessage() and queue() when no per-message duration is given. Does not affect show() calls that omit ms.
mountSelectorstringnoneCSS selector for an existing element to use as the toast surface. When the selector finds no match, the plugin falls back to creating a <div> inside the player container. When absent, the plugin always creates a new <div> inside the player container.

Methods

show(text, ms?)

TypeScript
show(text: string, ms?: number): void

Display a transient toast. The default duration is 3000 ms when ms is not provided. Any current toast is replaced immediately and its timer cancelled. The toast hides after ms milliseconds.

hide()

TypeScript
hide(): void

Hide the current transient toast and cancel any pending auto-hide timer. No-ops when the toast surface is not mounted.

displayMessage(data, ms?)

TypeScript
displayMessage(data: string | { text: string; durationMs?: number }, ms?: number): void

Structured alias for show(). Accepts a plain string or a { text, durationMs? } object. The ms argument takes priority over data.durationMs, which takes priority over the plugin’s durationMs option. Prefer show() for new call sites.

queue(messages)

TypeScript
queue(messages: ReadonlyArray<string | { text: string; durationMs?: number }>): void

Play a sequence of messages back-to-back, each displayed for its own duration. When no per-message duration is given, the plugin’s durationMs option (default 3000) applies. Calling queue() again or clear() cancels any in-flight sequence.

clear()

TypeScript
clear(): void

Cancel any in-flight queue(), hide the current toast, and reset all pending timers. Persistent messages are unaffected.

displayPersistent(text, id)

TypeScript
displayPersistent(text: string, id: string): void

Display a persistent overlay message that stays until removePersistent(id) is called. If a persistent message with the same id already exists, its text is updated in place without re-creating the element. The element carries role="status" and aria-live="polite" for screen readers.

removePersistent(id)

TypeScript
removePersistent(id: string): void

Remove a persistent message by its id. No-ops when no message with that id exists.

Accessibility

The toast surface carries role="status" and aria-live="polite" so screen readers announce updates without stealing focus. Persistent overlays get the same ARIA attributes.

Registration

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

const msg = player.getPlugin(MessagePlugin)!;

// Simple toast:
msg.show('Track added to queue');

// Sequence of messages:
msg.queue([
  'Shuffling playlist',
  { text: 'Done!', durationMs: 1500 },
]);

// Persistent "tap to play" prompt when autoplay is blocked:
msg.displayPersistent('Tap to start playback', 'autoplay-blocked');
player.on('play', () => msg.removePersistent('autoplay-blocked'));

See also