Skip to content

Writing Plugins

Plugin catalog

All plugins importable from @nomercy-entertainment/nomercy-music-player/plugins:

PluginidWhat it does
AutoAdvancePluginauto-advanceAdvances the queue on ended; optionally preloads and crossfades on trackEndingSoon.
LyricsPluginlyricsFetches and time-syncs lyrics via the cue parser registry; fires line / lineEnter / lineExit.
CastSenderPlugincast-senderChromecast sender, music-specific metadata + audio/mpeg content type; full session lifecycle from the core.
MediaSessionPluginmedia-sessionPublishes track metadata and artwork to the OS Media Session API (lock screen, notification panel).
MusicUiPluginmusic-uiSelf-contained HTML transport overlay: album art, track info, seek bar, controls, volume.
KeyHandlerPluginkey-handlerKeyboard shortcuts: space, arrows, m (core) + n, p, r, s (music-specific).
TabLeaderPlugintab-leaderWeb Locks single-tab-active enforcer, only one tab plays at a time.
MessagePluginmessageToast and persistent overlay surface: show(), queue(), displayPersistent().
EmbedPluginembedpostMessage bridge for host-page ↔ iframe player communication.
AudioGraphPluginaudio-graphWeb Audio AudioContext owner, prerequisite for all graph plugins. (from core)
EqualizerPluginequalizer10-band parametric EQ with pre-gain, built-in presets, and persistence. (from core)
SpectrumPluginspectrumFrequency-domain visualiser data via the shared AnalyserNode. (from core)
MixerPluginmixerPer-channel gain and panning. (from core)
CanvasPlugincanvas<canvas> RAF renderer, plug in a custom CanvasRenderFn for visualisations. (from core)
GroupListeningPlugingroup-listeningSynchronised multi-client listening. Roadmapped v2.1, throws NotImplementedError.
DrmPluginmusic-drmEME (Widevine / FairPlay / PlayReady). Roadmapped v2.1, throws NotImplementedError.
LiveTranscodingPluginlive-transcodingServer-coordinated live transcoding with backpressure. Roadmapped v2.1, throws NotImplementedError.

Music plugins extend the core’s Plugin base class with NMMusicPlayer<any> as the player type. This gives you typed access to all music-specific methods (backend(), crossfadeTo(), isTransitioning()) through this.player.

For the full plugin authoring guide including lifecycle, helpers, i18n, and the plugin contract, see Writing Plugins in the player core docs.

Quick example

TypeScript
import { Plugin } from '@nomercy-entertainment/nomercy-player-core';
import type { NMMusicPlayer } from '@nomercy-entertainment/nomercy-music-player';

interface NowPlayingOptions {
  endpoint: string;
}

export class NowPlayingPlugin extends Plugin<NMMusicPlayer<any>, NowPlayingOptions> {
  static override readonly id = 'now-playing';
  static override readonly version = '1.0.0';

  override use(): void {
    this.on('current', ({ item }) => {
      if (item) {
        void this.fetch(this.opts!.endpoint, {
          method: 'POST',
          body: JSON.stringify({
            name: item.name,
            artist: item.artist,
          }),
        });
      }
    });
  }
}

Registration:

TypeScript
player.addPlugin(NowPlayingPlugin, { endpoint: 'https://api.example.com/now-playing' });

Key differences from video plugins

  • this.player is typed as NMMusicPlayer<any>, not NMVideoPlayer
  • Available music events: current, trackEndingSoon, crossfadeStart, crossfadeComplete, repeat, shuffle, backend:changed
  • Music methods available: this.player.backend(), this.player.crossfadeTo(), this.player.isTransitioning()
  • Audio backend access: this.player.backend().outputNode(ctx) for graph plugins

See also