Skip to content

MusicPlaylistItem

The default track shape for NMMusicPlayer. Every item in the playlist array must satisfy this interface (or a type that extends it).

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

Interface

TypeScript
interface MusicPlaylistItem extends BasePlaylistItem {
  // Required
  id: string | number; // from BasePlaylistItem
  name: string;

  // Optional
  url?: string;
  cover?: string;
  artist?: string;
  album?: string;
  lyricsUrl?: string;
  duration?: number;
}

Fields

id (required)

TypeScript
id: string | number;

Unique identifier for the track. Used by the player to locate items in the queue (queueRemove, queueIndexOf, current). Must be unique within a session.

name (required)

TypeScript
name: string;

Track title. Displayed by MediaSessionPlugin on lock screens and system media controls. name is required on music items, unlike the video player’s title?, this field has no optional fallback.

url

TypeScript
url?: string

Audio source URL. Supports:

  • Direct MP3/AAC/FLAC/OGG: /D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.mp3 (relative to baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music')
  • HLS playlist: same pattern, hls.js is loaded automatically when native HLS is unsupported
  • Relative URL: resolved against baseUrl from config

When url is absent, the item can still be in the queue (the player skips it on natural advance and throws on an explicit load() call).

cover

TypeScript
cover?: string

Album art URL. Consumed by MediaSessionPlugin (pushes to OS lock screen), CastSenderPlugin (included in MusicTrackMediaMetadata), and MusicUiPlugin (renders in the UI overlay).

artist

TypeScript
artist?: string

Plain artist name string. Consumers with linked-entity data join or pick the primary before passing to the player.

MediaSessionPlugin uses this field to populate the artist field in OS media controls.

album

TypeScript
album?: string

Plain album name string. Consumers with linked-entity data join or pick the primary before passing to the player.

MediaSessionPlugin uses this field to populate the album field in OS media controls.

lyricsUrl

TypeScript
lyricsUrl?: string

URL of an LRC lyrics file for this track. LyricsPlugin reads this field when autoFetch: true (the default). On each current event, the plugin fetches the URL and parses it through the player core’s cue parser registry.

If you need a different resolution strategy (e.g. looking up lyrics from a server API by track ID), pass a getLyricsUrl function in LyricsPlugin options instead of populating this field per item.

duration

TypeScript
duration?: number

Track duration in seconds. This is a metadata-only fallback used by the player before the audio backend resolves the real duration from the file. When loadedmetadata fires and the backend returns duration > 0, the backend value takes precedence and this field is ignored.

Use it to populate seekbars immediately on track load without waiting for the audio metadata probe to complete, especially on slow connections.

TypeScript
{
  id: 'kjc-01',
  name: 'Thaw You Out',
  url: '/01%20Thaw%20You%20Out.mp3',
  duration: 204, // 3:24, seekbar renders immediately
}

Custom fields

The player is generic: NMMusicPlayer<T>. Extend MusicPlaylistItem with your own fields and pass the extended type at construction:

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

interface TrackItem extends MusicPlaylistItem {
  catalogueId: number;
  genre: string;
  isrc: string;
}

const player = nmMPlayer<TrackItem>('main');
// player.item() returns TrackItem | undefined
// player.queue() returns ReadonlyArray<TrackItem>

Custom fields are accessible in all event payloads (current, crossfadeStart, trackEndingSoon) and inside plugins via this.player.item() when the plugin’s player generic includes & WithCurrentItem<YourItemType>.

Full example

TypeScript
const playlist: MusicPlaylistItem[] = [
  {
    id: 'kjc-01',
    name: 'Thaw You Out',
    url: '/01%20Thaw%20You%20Out.mp3',
    cover: '/01%20Thaw%20You%20Out.jpg',
    lyricsUrl: '/01%20Thaw%20You%20Out.lrc',
    artist: 'Derek Clegg',
    album: 'KJC',
    duration: 204,
  },
  {
    id: 'kjc-02',
    name: 'Hope',
    url: '/02%20Hope.mp3',
    cover: '/02%20Hope.jpg',
    lyricsUrl: '/02%20Hope.lrc',
    artist: 'Derek Clegg',
    album: 'KJC',
    duration: 198,
  },
];

See also