Skip to content

Lyrics

Synced lyric display is provided by LyricsPlugin. See the full plugin reference at LyricsPlugin.

This page is a conceptual overview. Go to the plugin page for the complete API.

Setup

TypeScript
import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { LyricsPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(LyricsPlugin)
  .setup({
    baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music',
    playlist: [
      {
        id: 'kjc-01',
        name: 'Thaw You Out',
        url: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.mp3',
        lyricsUrl: '/D/Derek%20Clegg/%5B2010%5D%20KJC/01%20Thaw%20You%20Out.lrc',
        artist: 'Derek Clegg',
      },
    ],
  });

How it works

On every current event, LyricsPlugin reads item.lyricsUrl, fetches the LRC file, parses it through the core’s cue parser registry, and attaches a CueTracker. The tracker fires lineEnter / lineExit events as playback advances.

Parser selection is driven by URL file extension:

  • .lrc → LRC parser (pre-registered)
  • .vtt → WebVTT parser (pre-registered)
  • Custom extension → register a parser via player.registerCueParser(myParser)

Displaying lyrics

TypeScript
import { LyricsPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const lyricsEl = document.getElementById('lyrics')!;

// Build lyric sheet on first line event (cues are available from all() at this point):
player.on('plugin:lyrics:lineEnter', () => {
  if (lyricsEl.children.length === 0) {
    const lyricsPlugin = player.getPlugin(LyricsPlugin)!;
    const cues = lyricsPlugin.all();
    lyricsEl.innerHTML = cues.map((cue, index) => `<p data-index="${index}">${cue.payload.text}</p>`).join('');
  }
});

// Highlight active line:
player.on('plugin:lyrics:lineEnter', ({ text }) => {
  lyricsEl.querySelector('.active')?.classList.remove('active');
  for (const el of lyricsEl.querySelectorAll<HTMLElement>('p')) {
    if (el.textContent === text) {
      el.classList.add('active');
      el.scrollIntoView({ behavior: 'smooth', block: 'center' });
      break;
    }
  }
});

Custom resolver

When lyricsUrl is not on the track item, pass a getLyricsUrl function:

TypeScript
player.addPlugin(LyricsPlugin, {
  getLyricsUrl: (track) => `https://api.example.com/lyrics/${track.id}.lrc`,
});

See also