Cue Parsers - NoMercy Docs

Overview

The cue parser system parses timed text files (VTT, LRC, sprite-VTT) into CueList objects that the CueTracker consumes to emit time-aligned events. Custom parsers can be registered via player.registerCueParser() or at setup({ cueParsers }).

Most-recently-registered wins, so consumer parsers can override the player core’s built-ins for the same URL pattern.

`registerCueParser(parser, prepend?)`

Parameter	Type	Description
`parser`	`ICueParser`	Parser object
`prepend`	`boolean`	Insert at the back of the priority list (lower priority)

ICueParser interface

TypeScript

interface ICueParser<T = unknown> {
  /** Stable identifier for this parser. */
  readonly id: string;
  /** Return true when this parser can handle the given URL or content-type. */
  canParse(url: string, contentType?: string): boolean;
  /**
   * Parse raw text into a CueList. The player fetches the file first, then
   * calls parse() with the raw content. The parser never fetches anything itself.
   * opts.baseUrl is forwarded for parsers that need to resolve relative URLs
   * inside the content (e.g. sprite VTT image paths).
   */
  parse(raw: string, opts?: { baseUrl?: string }): CueList<T>;
}

`unregisterCueParser(id)`

Unregister a cue parser by id.

`resolveCueParser(url)`

Resolve the registered parser for the given URL. Returns undefined when no parser matches.

Returns: ICueParser | undefined

Built-in parsers

All three are exported from the player core root.

`parseVtt(text)`

Parse a WebVTT string into cues. Returns { cues } where each cue has start, end, payload.

TypeScript

import { parseVtt } from '@nomercy-entertainment/nomercy-player-core';
const { cues } = parseVtt(vttText);

`parseVttSubtitles(text)`

Parse a subtitle-oriented VTT (with markup, positioning cues). Returns a CueList<VTTSubtitlePayload>.

`parseVttSprite(text)`

Parse a sprite-preview VTT (thumbnail strip). Returns a CueList<VTTSpritePayload> where each entry carries x, y, w, h, and the sprite image URL.

`parseLrc(text)`

Parse an LRC lyrics file. Returns a CueList<LrcPayload> where each cue carries text and optional extended metadata.

TypeScript

import { parseLrc } from '@nomercy-entertainment/nomercy-player-core';
const { cues } = parseLrc(lrcText);

CueTracker

CueTracker drives the timed-cue event pipeline. Given a CueList, it attaches to a player and emits cue:enter / cue:exit as the playback position crosses cue boundaries.

TypeScript

import { CueTracker } from '@nomercy-entertainment/nomercy-player-core';

const tracker = new CueTracker(cueList, { trackerId: 'my-lyrics' });
tracker.on('enter', (cue) => showLyric(cue.payload.text));
tracker.on('exit', (cue) => hideLyric());
tracker.attach(player); // starts listening to player.on('time', ...)

CueTrackerOptions

Field	Type	Default	Description
`trackerId`	`string`	none	Stable identifier (surfaces in cue payloads)
`tolerance`	`number`	`0`	Seconds of look-ahead for early entry
`historyMax`	`number`	`32`	Cap on recently-entered cues kept by `history(n)`

Cleanup

Call tracker.dispose() to detach from the player and release listeners. The media-tracks mixin calls this automatically when switching subtitle tracks.

Custom parser example (TTML)

The player fetches the file, then calls parse() with the raw text. Your parser receives the content string, not a URL.

TypeScript

player.registerCueParser({
  id: 'ttml',
  canParse: (url) => url.endsWith('.ttml') || url.endsWith('.xml'),
  parse(raw) {
    return parseTTML(raw);
  },
});