Skip to content

Lyric Source

Port for resolving lyrics URLs, the ILyricSource contract. LyricsPlugin does not consume an ILyricSource directly — bridge one by passing getLyricsUrl: (track) => mySource.resolve(track) to the plugin (see the example below). The resolved URL is handed to the player core’s cue parser registry for fetching and parsing.

TypeScript
import type { ILyricSource } from '@nomercy-entertainment/nomercy-music-player/adapters/lyric-source';

Interface

TypeScript
interface ILyricSource<T extends BasePlaylistItem = BasePlaylistItem> {
  readonly id: string;
  resolve(item: T): string | undefined;
}

id

Human-readable identifier. Used in logging and debug tooling.

resolve(item)

Resolve the lyrics URL for item. Return a URL string for LyricsPlugin to fetch, or undefined when no lyrics are available for this track.

Built-in adapter

LrcFileSource

TypeScript
import { LrcFileSource } from '@nomercy-entertainment/nomercy-music-player/adapters/lyric-source';

Reads the lyricsUrl field from MusicPlaylistItem. This is the default behavior when LyricsPlugin has no custom getLyricsUrl option configured.

Custom implementation

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

class ApiLyricSource implements ILyricSource<MusicPlaylistItem> {
  readonly id = 'api-lyric-source';

  resolve(item: MusicPlaylistItem): string | undefined {
    if (!item.id) return undefined;
    return `https://api.example.com/lyrics/${item.id}.lrc`;
  }
}

Pass it through LyricsPlugin options:

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

const source = new ApiLyricSource();
player.addPlugin(LyricsPlugin, {
  getLyricsUrl: (track) => source.resolve(track),
});

See also