Skip to content

Message

MessagePlugin gives the player a small notification surface. Register it when you want on-screen toast messages, whether from your own code or from other plugins like KeyHandlerPlugin that need to show OSD feedback for speed changes, subtitle cycling, and similar actions.

Plugin id

'message'

Import

TypeScript
import { MessagePlugin } from '@nomercy-entertainment/nomercy-video-player/plugins';
import type { MessageInput, MessageOptions } from '@nomercy-entertainment/nomercy-video-player/plugins';

What it does

MessagePlugin manages two kinds of overlays inside the player container. Transient toasts appear for a set duration then hide automatically. Persistent overlays stay until you explicitly remove them, useful for blocking states like an autoplay-blocked “Tap to play” prompt.

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

KeyHandlerPlugin calls player.displayMessage(text) when that method exists on the player object, and emits a display-message event unconditionally. MessagePlugin is not involved in that path; the two plugins are independent.

Options

OptionTypeDefaultDescription
durationMsnumber3000Fallback display duration in milliseconds, used by displayMessage() and queue() items that do not carry their own duration. Does not affect show() calls that omit ms.
mountSelectorstringnoneCSS selector passed to document.querySelector() to locate an existing element in which to mount the toast surface. When the selector matches nothing, the plugin falls back to creating a <div> inside the player container. When absent the plugin always uses the default container mount.

Methods

show

TypeScript
plugin.show(text: string, ms: number = 3000): void

Display a transient toast. When ms is omitted the toast hides after 3000 ms, regardless of durationMs in options. Replaces any currently visible toast and resets the timer.

hide

TypeScript
plugin.hide(): void

Hide the current toast and cancel any pending auto-hide timer.

displayMessage

TypeScript
plugin.displayMessage(data: MessageInput, ms?: number): void

Accepts a plain string or a { text, durationMs? } object. Falls back to opts.durationMs then 3000 ms when no duration is provided. Prefer show() for new call sites; this method exists for callers that pass structured message objects.

queue

TypeScript
plugin.queue(messages: ReadonlyArray<MessageInput>): void

Play a sequence of messages back-to-back, each for its own duration. Calling queue() again or clear() cancels any in-flight run immediately.

TypeScript
const msg = player.getPlugin(MessagePlugin);

msg?.queue([
  'Loading…',
  { text: 'Almost there!', durationMs: 1500 },
  'Done.',
]);

clear

TypeScript
plugin.clear(): void

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

displayPersistent

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

Display a named persistent overlay. If a persistent message with the same id already exists, its text is updated in-place.

removePersistent

TypeScript
plugin.removePersistent(id: string): void

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

Registration

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player';
import { MessagePlugin } from '@nomercy-entertainment/nomercy-video-player/plugins';

const player = nmplayer('player')
  .addPlugin(MessagePlugin, { durationMs: 2500 })
  .setup({
    baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films',
    playlist: [
      {
        id: 'sintel',
        title: 'Sintel',
        url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8',
      },
    ],
  });

Showing a toast from consumer code

TypeScript
player.on('ended', () => {
  const msg = player.getPlugin(MessagePlugin);

  msg?.show('Playback complete', 3000);
});

See also