Skip to content

VideoPlaylistItem

VideoPlaylistItem is the shape of each item in the player’s playlist. Pass it in VideoPlayerConfig.playlist or supply it to player.item(item).

TypeScript
import type { VideoPlaylistItem } from '@nomercy-entertainment/nomercy-video-player';

Fields

Media source

FieldTypeRequiredDescription
idstring | numberYesUnique item id — the only structurally required field
urlstringFor playbackHLS manifest URL (.m3u8) or progressive MP4 URL
titlestringNoDisplay title shown in the UI and MediaSession metadata
durationnumberNoDuration in seconds. Used by the UI before the backend loads metadata

Cover art

Three field names are accepted in priority order: image → poster → thumbnail. The player reads whichever is first populated. Use any name your backend already uses.

FieldTypeDescription
imagestringPoster/cover URL, highest priority
posterstringPoster URL, second priority
thumbnailstringThumbnail URL, third priority

When VideoPlayerConfig.baseImageUrl is set, relative paths like /abc.jpg are resolved against that base. Absolute URLs pass through unchanged.

Subtitles

TypeScript
subtitles?: SubtitleTrackRef[];

Typed array of subtitle tracks. Each entry is a SubtitleTrackRef (re-export of the core’s SubtitleTrack):

TypeScript
import type { SubtitleTrackRef } from '@nomercy-entertainment/nomercy-video-player';

// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'
const item: VideoPlaylistItem = {
  url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8',
  subtitles: [
    {
      id: 'eng',
      kind: 'subtitles',
      label: 'English',
      language: 'en',
      url: '/Sintel.(2010)/subtitles/Sintel.(2010).NoMercy.eng.full.vtt',
    },
    {
      id: 'dut',
      kind: 'subtitles',
      label: 'Dutch',
      language: 'nl',
      url: '/Sintel.(2010)/subtitles/Sintel.(2010).NoMercy.dut.full.vtt',
    },
  ],
};

The player uses defaultSubtitleLanguage from config to auto-select a track at load time.

Chapters

TypeScript
chapters?: ChapterRef[];

Typed array of chapter markers. Each ChapterRef is a { index: number; start: number; end: number; title: string } (re-export of the core’s Chapter). The player renders these in the progress bar when the DesktopUiPlugin is active.

TypeScript
import type { ChapterRef } from '@nomercy-entertainment/nomercy-video-player';

chapters: [
  { index: 0, title: 'Intro',   start: 0,    end: 90   },
  { index: 1, title: 'Act 1',   start: 90,   end: 1200 },
  { index: 2, title: 'Credits', start: 3400, end: 3480 },
],

Skip markers

TypeScript
skippers?: SkipperData;

Optional skip ranges consumed by the SkipperPlugin. Each range has start and end in seconds.

TypeScript
import type { SkipperData } from '@nomercy-entertainment/nomercy-video-player';

skippers: {
  intro:   { start: 3,    end: 92   },
  recap:   { start: 0,    end: 45   },
  credits: { start: 3400, end: 3480 },
},

Thumbnail sprites

TypeScript
previewSpriteUrl?: string;

URL of a WebVTT sprite manifest used by the progress bar hover thumbnail. This is the canonical field; DesktopUiPlugin reads it to render the progress-bar hover thumbnails.

TypeScript
// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'
previewSpriteUrl: '/Sintel.(2010)/thumbs_256x109.vtt',

Fonts (for ASS/SSA subtitles)

TypeScript
fonts?: FontTrackRef[];

Font manifests for ASS/SSA subtitle rendering via OctopusPlugin. Each entry is either a fonts.json manifest URL or a direct font file URL.

TypeScript
import type { FontTrackRef } from '@nomercy-entertainment/nomercy-video-player';

// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Anime'
fonts: [
  { file: '/Rail.Wars!.(2014)/Rail.Wars!.S00E00/fonts.json', label: 'Cosmos fonts' },
],

This is the canonical alternative to the deprecated tracks field for fonts.

Series metadata

FieldTypeDescription
showstringSeries/show title shown in the top bar and sent as MediaSession artist
seasonnumberSeason number (1-based). Combined with episode to render “S01E03”
episodenumberEpisode number (1-based)

Continue-watching progress

TypeScript
progress?: WatchProgress;

Consumer-supplied watch progress. The player reads this to render the playlist menu progress bar. The player does not write to this field, so persistence is the consumer’s responsibility.

TypeScript
import type { WatchProgress } from '@nomercy-entertainment/nomercy-video-player';

progress: {
  timestamp: Date.now(),   // Unix epoch milliseconds of last watch session
  percentage: 42,          // 0–100 percent watched
},

Deprecated: tracks (v1 compat only)

The tracks field was removed from VideoPlaylistItem in v2. It exists only on VideoPlaylistItemV1Compat exported from @nomercy-entertainment/nomercy-video-player/compat.

TypeScript
import { normalizeVideoItem } from '@nomercy-entertainment/nomercy-video-player/compat';

// Pass legacy items through the normalizer before handing them to the v2 player.
const v2Item = normalizeVideoItem(legacyItemWithTracks);

normalizeVideoItem maps tracks entries to their typed v2 counterparts by kind: 'subtitles' (or 'text', or a kindless entry with a language/label) → subtitles[], 'thumbnails' → previewSpriteUrl, 'fonts' → fonts[]. A legacy 'chapters' track’s file is also promoted to previewSpriteUrl when no thumbnails entry is present. Use the typed fields (subtitles, chapters, previewSpriteUrl, fonts) in new code.

Full example

TypeScript
import type { VideoPlaylistItem } from '@nomercy-entertainment/nomercy-video-player';

// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'
const item: VideoPlaylistItem = {
  title: 'Tears of Steel',
  url: '/Tears.of.Steel.(2012)/Tears.of.Steel.(2012).NoMercy.m3u8',
  image: 'https://image.tmdb.org/t/p/w780/aB67tezxbHnbiTW6Vt0VQ5tBnxv.jpg',
  duration: 12 * 60 + 10,
  subtitles: [
    {
      id: 'eng',
      kind: 'subtitles',
      label: 'English',
      language: 'en',
      url: '/Tears.of.Steel.(2012)/subtitles/Tears.of.Steel.(2012).NoMercy.eng.full.vtt',
    },
  ],
  chapters: [{ index: 0, title: 'Opening', start: 0, end: 120 }],
  previewSpriteUrl: '/Tears.of.Steel.(2012)/previews.vtt',
  skippers: {
    intro: { start: 5, end: 90 },
  },
  progress: { timestamp: Date.now(), percentage: 0 },
};

Type imports

TypeScript
import type {
  VideoPlaylistItem,
  SubtitleTrackRef,
  ChapterRef,
  FontTrackRef,
  SkipperData,
  WatchProgress,
} from '@nomercy-entertainment/nomercy-video-player';

See also