Overview

The player core ships a set of opt-in plugins that cover the capabilities every player needs, without forcing you to load anything you don’t use. None are registered automatically, so your bundle only pays for what you add. Most are re-exported from the main @nomercy-entertainment/nomercy-player-core barrel; a few use dedicated subpath imports to keep tree-shaking effective.

Each plugin entry below follows the same shape: what it does, its plugin id, import path, options table (every field from the source Options interface), events table, a registration example, and public methods where the plugin exposes them.

Main barrel exports

Import from @nomercy-entertainment/nomercy-player-core.

AudioGraphPlugin

Plugin id: 'audio-graph' | Import: import { AudioGraphPlugin, audioGraphPlugin } from '@nomercy-entertainment/nomercy-player-core'

Foundation plugin that owns the Web Audio signal chain. Every other audio plugin in the core (EqualizerPlugin, SpectrumPlugin, VisualizationPlugin, MixerPlugin) requires this one to be registered first.

On use() it creates (or reuses) an AudioContext, wraps the backend’s media element in a MediaElementAudioSourceNode, and wires the baseline chain: source → destination. Subsequent plugins extend the chain via insertEffect(). The chain topology is:

Options (AudioGraphOptions):

Events (AudioGraphEvents):

Registration example:

import { AudioGraphPlugin } from '@nomercy-entertainment/nomercy-player-core';

player.addPlugin(AudioGraphPlugin, { latencyHint: 'playback', fftSize: 2048 });

Public methods:

CanvasPlugin

Plugin id: 'canvas' | Import: import { CanvasPlugin, canvasPlugin } from '@nomercy-entertainment/nomercy-player-core'

Mounts a single <canvas> into the player container and runs the shared RAF render loop. Visualization plugins register per-frame callbacks via addRenderer() rather than managing their own canvases. Without this plugin no canvas is created and no animation frames are requested, so there is zero cost when not used.

Options (CanvasOptions):

Events (CanvasEvents):

Registration example:

import { CanvasPlugin } from '@nomercy-entertainment/nomercy-player-core';

player.addPlugin(CanvasPlugin, { fps: 60, compositeMode: 'clear' });

const canvas = player.getPlugin(CanvasPlugin);
const stop = canvas.addRenderer((ctx, deltaMs) => {
  ctx.fillStyle = '#ff0000';
  ctx.fillRect(0, 0, 10, 10);
});
// Remove when no longer needed:
stop();

Public methods:

CastSenderPlugin

Plugin id: 'cast-sender' | Import: import { CastSenderPlugin, castSenderPlugin } from '@nomercy-entertainment/nomercy-player-core'

Chromecast Web Sender SDK bridge. Forwards current, play, pause, stop, seek, volume, and mute player events to the active Cast session via RemotePlayerController. Mirrors receiver state back to the player. In non-Chromium browsers (or when the Cast SDK is absent) the bridge stays passive, so connect() throws BrowserPolicyError and all forwarders no-op.

This is a base class. The video and music player packages each ship a thin subclass that overrides defaultContentType() and buildMetadata() for their media type.

Options (CastSenderOptions):

Events (CastSenderEvents):

Registration example:

import { CastSenderPlugin } from '@nomercy-entertainment/nomercy-player-core';

player.addPlugin(CastSenderPlugin, {
  chromecastAppId: 'YOUR_APP_ID',
  resumeLocalOnDisconnect: true,
});

const cast = player.getPlugin(CastSenderPlugin);
await cast.connect(); // opens device picker

Public methods:

EqualizerPlugin

Plugin id: 'equalizer' | Import: import { EqualizerPlugin, equalizerPlugin } from '@nomercy-entertainment/nomercy-player-core'

10-band parametric EQ with pre-gain, built-in named presets, custom presets, and persistence. Inserts a GainNode (pre-gain) followed by 10 peaking BiquadFilterNodes into the audio graph as 'post' effects. Requires AudioGraphPlugin.

Options (EqualizerOptions):

Events (EqualizerEvents):

Registration example:

import { AudioGraphPlugin, EqualizerPlugin } from '@nomercy-entertainment/nomercy-player-core';

player
  .addPlugin(AudioGraphPlugin, { latencyHint: 'playback' })
  .addPlugin(EqualizerPlugin, { persistKey: 'player-eq' });

const eq = player.getPlugin(EqualizerPlugin);
eq?.band('Pre', 3.0);  // set pre-gain to +3 dB
eq?.band('Pre');       // read current pre-gain
eq?.band(32, 4.0);     // set 32 Hz band to +4 dB
eq?.preset('Rock');

Public methods:

MixerPlugin

Plugin id: 'mixer' | Import: import { MixerPlugin, mixerPlugin } from '@nomercy-entertainment/nomercy-player-core'

Master gain (GainNode) and stereo pan (StereoPannerNode) stage in the audio graph. Sits at the end of the chain just before AudioContext.destination. Requires AudioGraphPlugin.

Options (MixerOptions):

Events (MixerEvents):

Registration example:

import { AudioGraphPlugin, MixerPlugin } from '@nomercy-entertainment/nomercy-player-core';

player
  .addPlugin(AudioGraphPlugin)
  .addPlugin(MixerPlugin, { gain: 0, persistKey: 'player-mixer' });

const mixer = player.getPlugin(MixerPlugin);
mixer?.gain(6);     // +6 dB boost
mixer?.gain();      // read current gain in dB
mixer?.pan(-0.5);   // pan slightly left
mixer?.muted(true); // mute

Public methods:

SpectrumPlugin

Plugin id: 'spectrum' | Import: import { SpectrumPlugin, spectrumPlugin } from '@nomercy-entertainment/nomercy-player-core'

FFT analyser that produces per-frame frequency, waveform, and band-energy data. Acquires the shared AnalyserNode from AudioGraphPlugin and emits a frame event on every RAF tick. VisualizationPlugin subclasses consume these frames. Requires AudioGraphPlugin.

Options (SpectrumOptions):

Events (SpectrumEvents):

Registration example:

import { AudioGraphPlugin, SpectrumPlugin } from '@nomercy-entertainment/nomercy-player-core';

player
  .addPlugin(AudioGraphPlugin)
  .addPlugin(SpectrumPlugin, { fftSize: 2048 });

player.on('plugin:spectrum:frame', ({ frame, energy }) => {
  drawBars(frame.frequency);
  updateMeter(energy.bass);
});

Public methods:

VisualizationPlugin

Plugin id: 'visualization' (base; subclasses must override) | Import: import { VisualizationPlugin } from '@nomercy-entertainment/nomercy-player-core'

Abstract base class for canvas-based audio visualizations. Subclass it, override render(ctx, frame), and register with the player. The base class handles wiring CanvasPlugin and SpectrumPlugin together so every render() call receives a fresh VisualizationFrame. Requires CanvasPlugin and SpectrumPlugin.

Options (VisualizationOptions):

Events (VisualizationEvents):

Registration example:

import {
  AudioGraphPlugin,
  CanvasPlugin,
  SpectrumPlugin,
  VisualizationPlugin,
} from '@nomercy-entertainment/nomercy-player-core';

class MyBars extends VisualizationPlugin {
  static override readonly id = 'myapp:bars';

  protected override render(ctx: CanvasRenderingContext2D, frame) {
    for (let i = 0; i < frame.frequency.length; i++) {
      const height = (frame.frequency[i] / 255) * ctx.canvas.height;
      ctx.fillStyle = `hsl(${i * 2}, 100%, 50%)`;
      ctx.fillRect(i * 3, ctx.canvas.height - height, 2, height);
    }
  }
}

player
  .addPlugin(AudioGraphPlugin)
  .addPlugin(SpectrumPlugin)
  .addPlugin(CanvasPlugin)
  .addPlugin(MyBars);

Public methods:

Override hooks (protected):

A working reference implementation, WaveformVisualization (id 'fillz:waveform'), ships in the same module and strokes the time-domain waveform as an oscilloscope line.

EmbedPlugin

Plugin id: 'embed' | Import: import { EmbedPlugin, embedPlugin } from '@nomercy-entertainment/nomercy-player-core'

Cross-origin postMessage bridge for embedding the player inside an <iframe>. Listens on window for inbound nm:command messages from the host page, validates origins, and dispatches to the player. Subscribes to player events and forwards them outward as nm:event messages.

Required <iframe> attributes for full functionality:

<iframe
  src="..."
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media"
  allowfullscreen
></iframe>

autoplay is load-bearing: without it MediaSessionPlugin never activates, so OS-level controls never appear.

Options (EmbedOptions):

Inbound commands (EmbedCommand): play, pause, stop, seek (with time), volume (with level), mute, unmute, next, previous.

Outbound events (EmbedEventMessage): ready, play, pause, ended, time (with time), volume (with level), mute (with muted), error (with code+severity).

Registration example:

import { EmbedPlugin } from '@nomercy-entertainment/nomercy-player-core';

// Inside the iframe:
player.addPlugin(EmbedPlugin, {
  allowedOrigins: 'https://example.com',
});

// On the host page:
const iframe = document.querySelector('iframe');
iframe.contentWindow.postMessage({ type: 'nm:command', action: 'play' }, 'https://player.example.com');
window.addEventListener('message', (event) => {
  if (event.data.type === 'nm:event') console.log(event.data.name, event.data);
});

Public methods:

Subpath imports

These plugins are not in the main barrel. Use their dedicated subpath imports.

KeyHandlerPlugin

Plugin id: 'key-handler' | Import: import { KeyHandlerPlugin, keyHandlerPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/key-handler'

Keyboard binding router. Attaches a single keydown listener to the configured scope and dispatches events to registered combo callbacks. Keys silently no-op when the event target is an <input>, <textarea>, <select>, or contenteditable element.

Default bindings:

Options (KeyHandlerOptions):

Registration example:

import { KeyHandlerPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/key-handler';

player.addPlugin(KeyHandlerPlugin, {
  scope: 'container',
  bindings: {
    'shift+ArrowLeft': (player) => player.rewind(30),
  },
});

Public methods:

MediaSessionPlugin

Plugin id: 'media-session' | Import: import { MediaSessionPlugin, mediaSessionPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/media-session'

Bridges the player’s transport state to the operating system via navigator.mediaSession. Provides lock-screen artwork, hardware media key handling, Bluetooth remote controls, and OS Now Playing widgets. Silently no-ops in environments without navigator.mediaSession (Node, JSDOM, older WebViews).

Automatically wires on use(): current → pushes metadata; play/pause/ended → playbackState; time/seek → setPositionState. OS action handlers registered: play, pause, stop, previoustrack, nexttrack, seekbackward, seekforward, seekto.

Options (MediaSessionOptions): none. The interface is empty, reserved for future options.

Registration example:

import { MediaSessionPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/media-session';

player.addPlugin(MediaSessionPlugin);

Public methods:

Override hooks (protected):

MessagePlugin

Plugin id: 'message' | Import: import { MessagePlugin, messagePlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/message'

Toast and overlay-message surface for the player. UI plugins and consumers call show('text') to display a transient notification. The plugin manages timing and teardown automatically. The toast surface carries role="status" and aria-live="polite" for screen reader compatibility.

Two modes: transient (show, queue), which auto-hides after a duration; and persistent (displayPersistent, removePersistent), which stays until explicitly removed.

Options (MessageOptions):

Registration example:

import { MessagePlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/message';

player.addPlugin(MessagePlugin, { durationMs: 3000 });

const msg = player.getPlugin(MessagePlugin);
msg?.show('Subtitle track loaded');
msg?.show('Buffering…', 0);  // 0 ms = stays until dismissed or replaced
msg?.hide();
msg?.queue(['Loading…', { text: 'Almost there!', durationMs: 1500 }, 'Done.']);

Public methods:

TabLeaderPlugin

Plugin id: 'tab-leader' | Import: import { TabLeaderPlugin, tabLeaderPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/tab-leader'

Web Locks-based cross-tab leader election. Only one tab on the same origin holds the named lock at a time. When a second tab calls requestLock(), it queues behind the current holder; the browser hands the lock over when the first tab releases it or is closed.

Browser support: Web Locks (Chrome 69+, Firefox 96+, Safari 15.4+). In environments without navigator.locks the plugin emits unsupported and becomes a no-op, so playback is unaffected.

Options (TabLeaderOptions):

Events (TabLeaderEvents):

Registration example:

import { TabLeaderPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/tab-leader';

player.addPlugin(TabLeaderPlugin, {
  getLockKey: () => `nomercy-leader-${serverId}`,
  onLost: 'pause',
});

const leader = player.getPlugin(TabLeaderPlugin);
leader?.isLeader(); // boolean

player.on('plugin:tab-leader:leader-released', () => player.pause());

Public methods:

Audio chain registration order

Audio plugins must be registered in dependency order: AudioGraphPlugin first, then the plugins that depend on it.

import {
  AudioGraphPlugin,
  CanvasPlugin,
  EqualizerPlugin,
  MixerPlugin,
  SpectrumPlugin,
} from '@nomercy-entertainment/nomercy-player-core';

player
  .addPlugin(AudioGraphPlugin, { latencyHint: 'playback' })
  .addPlugin(EqualizerPlugin, { persistKey: 'player-eq' })
  .addPlugin(MixerPlugin, { gain: 0 })
  .addPlugin(SpectrumPlugin, { fftSize: 2048 })
  .addPlugin(CanvasPlugin);

See also

• Plugin Registration: addPlugin, getPlugin, removePlugin
• Events Reference: plugin:installed, plugin:failed
• Recipes: Media Session: full MediaSessionPlugin setup guide