Installation

Requirements

• Node.js 18 or later (tooling only, the player itself runs in any modern browser)
• A module bundler (Vite, Webpack, Rollup, or similar)

Install the package

npm install @nomercy-entertainment/nomercy-music-player@beta

The package-manager toggle, pinned to the top right, switches this command to yarn, pnpm, or bun.

CDN (no bundler)

You can drop the player onto a page without a bundler. Load hls.js first (the IIFE bundle reads it from the Hls global), then the player bundle, which exposes a nmMPlayer global.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/hls.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@nomercy-entertainment/nomercy-music-player@beta/dist/nomercy-music-player.iife.js"></script>

Built-in plugins are not part of the IIFE bundle, so use the npm install above when you need them.

Import paths

The package ships several import paths:

// Main player + types
import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import type {
  MusicPlaylistItem,
  MusicPlayerConfig,
  IMusicPlayer,
} from '@nomercy-entertainment/nomercy-music-player';

// Plugins, always import from the /plugins subpath
import {
  AutoAdvancePlugin,
  LyricsPlugin,
  MediaSessionPlugin,
} from '@nomercy-entertainment/nomercy-music-player/plugins';

Importing plugins from the main entry point is not supported, always use /plugins.

TypeScript

The package ships full TypeScript declarations. No @types/ package is needed.

The recommended type for a consumer-held player reference is IMusicPlayer<T>:

import type { IMusicPlayer, MusicPlaylistItem } from '@nomercy-entertainment/nomercy-music-player';

let player: IMusicPlayer<MusicPlaylistItem>;

Use the concrete NMMusicPlayer<T> type only when you need access to internals not exposed on the interface.

Browser support

HLS streams

HLS support is handled by hls.js. It is a production dependency of @nomercy-entertainment/nomercy-player-core, which this package depends on, so it arrives transitively when you install @nomercy-entertainment/nomercy-music-player. No separate install is needed. The library is loaded automatically when an .m3u8 URL is detected on a browser that does not support native HLS.

On Safari and iOS, native HLS is used directly and hls.js is not loaded.

What to read next

• Quick Start, minimal working player in under 30 lines
• Configuration, all setup() options