Skip to content

Overview

Loading methods mount a single item or a remote playlist into the player. load() is the core action: it dispatches beforeLoad, resolves the URL through the auth pipeline, and calls the backend’s load(url). A monotonic epoch guard prevents race conditions when load() is called in rapid succession.

load(item, opts?)

Load a single playlist item into the player.

Before loading:

  1. Dispatches beforeLoad; a listener may preventDefault(), which emits loadPrevented and returns without touching the backend.
  2. Resolves item.url through auth.transformUrl when configured.
  3. Resolves sidecar track URLs via resolveItemTrackUrls (subtitle, chapter file URLs are made absolute relative to baseUrl).

Phase transitions: the player enters loading while the backend mounts, then returns to ready on success. The transition is skipped when called during initial setup to avoid a flash.

After loading:

  • If opts.startAt is set, seeks to that timestamp.
  • If opts.fadeIn is set, ramps volume from 0 to the current level over that many seconds.
  • Emits mediaReady on success.
ParameterTypeDefaultDescription
item.urlstringnoneRequired. The playable media URL
opts.slot'current' | 'next''current''next' preloads without interrupting playback
opts.startAtnumbernoneStart position in seconds
opts.fadeInnumbernoneVolume fade-in duration in seconds
opts.sourceActionSource'user'Source attribution
opts.autoplaybooleanfalseCall play() after load resolves

Returns: Promise<void>

Events emitted:

  • beforeLoad: cancellable
  • loadPrevented: fires instead when prevented
  • mediaReady: fires after a successful load

Throws: core:media/missing-url when item.url is absent; core:player/backend-missing when no backend is wired.

TypeScript
// player was set up with:
// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'

// basic load and play
await player.load({
  id: 'sintel',
  title: 'Sintel',
  url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8',
});
await player.play();

// load with resume position
await player.load(
  {
    id: 'cosmos',
    url: '/Tears.of.Steel.(2012)/Tears.of.Steel.(2012).NoMercy.m3u8',
  },
  { startAt: 422, autoplay: true },
);

loadQueue(url, parser?)

Fetch a remote playlist URL and replace the current queue with the parsed result.

The request goes through the same auth pipeline as all other player fetches. When parser is omitted, the response body is parsed as JSON. Supply a custom parser for M3U, XSPF, or other playlist formats.

ParameterTypeDescription
urlstringRemote playlist URL
parser(raw: string) => T[]Optional custom parser

Returns: Promise<void>

Events emitted:

  • playlistResolving with { url } before the fetch
  • playlistReady with { length } on success
  • playlistResolveError and error on failure (and re-throws)
TypeScript
await player.loadQueue('https://api.nomercy.tv/v1/library/movie/1/playlist.json');

resolveItemTrackUrls(item)

Resolve every relative sidecar track URL on an item against baseUrl and auth.transformUrl. Items with no tracks are returned unchanged.

Also populates chapters from a sidecar tracks: [{ kind: 'chapters', file }] VTT when the item carries no inline chapters.

Called automatically by load(), this method is exposed for consumers building custom preload pipelines.

Returns: Promise<T> (the item, potentially with resolved track URLs)

See also