Skip to content

Interface

TypeScript
interface BasePlaylistItem {
  id: string | number;
  title?: string;
  image?: string;
}

id is the stable identity used by the queue, backlog, cursor, and queueIndexOf. It must be unique within a session but does not need to be globally unique.

title and image are the canonical cross-library fields for display name and cover art. Consumer code targeting both the video and music players should populate these fields; domain-specific code may use the library’s own field names in addition.

Library extensions

Each library extends BasePlaylistItem with domain-specific fields.

Video player, VideoPlaylistItem

FieldTypeDescription
title?stringDisplay title
image?stringPoster / thumbnail URL
poster?stringAlias for image
thumbnail?stringSmall thumbnail (for hover previews)
url?stringRequired by load(), the playable media URL
subtitles?SubtitleTrackRef[]Subtitle sidecar files
chapters?ChapterRef[]Resolved chapter list ({ index, start, end, title })
previewSpriteUrl?stringVTT sprite sheet for seek-preview thumbnails
fonts?FontTrackRef[]Font manifests for ASS/SSA subtitles

Music player, MusicPlaylistItem

FieldTypeDescription
namestringTrack name (required by the music player)
cover?stringCover art URL (aliases image)
artist?string | ArtistArtist name or object
album?string | AlbumAlbum name or object
url?stringRequired by load(), the audio file URL

Subtitle and chapter sidecars

Domain sidecars live in typed fields on the library item, not a generic tracks array. On VideoPlaylistItem, subtitle files go in subtitles and resolved chapters in chapters:

TypeScript
// baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films'
{
  id: 'sintel',
  title: 'Sintel',
  url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8',
  subtitles: [
    {
      id: 'eng-full',
      kind: 'subtitles',
      language: 'eng',
      label: 'English',
      url: '/Sintel.(2010)/subtitles/Sintel.(2010).NoMercy.eng.full.vtt',
    },
  ],
  chapters: [
    { index: 0, start: 0, end: 270, title: 'Opening' },
  ],
}

SubtitleTrack.kind is 'subtitles', 'captions', or 'descriptions'. Chapters take resolved { index, start, end, title } objects. To load chapters from a VTT file instead, the core also accepts a loose sidecar array, tracks: [{ kind: 'chapters', file: '...vtt' }], which it fetches and parses when the item ships no inline chapters (see Chapters).

See also