Overview

Media track methods read and select subtitle tracks, audio tracks, and quality levels. Read methods delegate to the active backend; setters emit the corresponding event so plugins and UI components react regardless of backend support.

Subtitle track lists combine backend-managed tracks (from HLS manifests) with sidecar VTT tracks from the item’s tracks field. The flat merged list is what consumers index into.

Subtitles

subtitles()

The full subtitle track list, backend-managed tracks first, sidecar VTT tracks appended after. Returns [] before a backend is mounted or when no item is active.

Returns: ReadonlyArray<SubtitleTrack>

interface SubtitleTrack {
  id: string;
  language?: string;
  label: string;
  kind?: 'subtitles' | 'captions' | 'descriptions';
  type?: string;
  url: string;
  default?: boolean;
}

subtitle(idx?)

Read or write the active subtitle track.

Read: subtitle() returns { index, track } for the selected track, or null when subtitles are off.

Write: subtitle(idx) selects the track at idx. Pass null or a negative number to disable subtitles. For backend-managed tracks the backend is notified directly; for sidecar tracks a CueTracker is started and feeds subtitleCue events.

Events emitted: subtitle with { track: idx | null }; subtitleCue with { cues: [], language } when disabling.

subtitleStyle(patch?)

Read or write the subtitle style. A partial patch is merged onto the active style.

subtitleStyle is part of the media-tracks mixin but is not declared on the generic IPlayer interface. Type the player as NMVideoPlayer (or NMMusicPlayer) to access it — the concrete classes expose it.

Events emitted: subtitleStyle with the merged style

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

declare const player: NMVideoPlayer;
player.subtitleStyle({ fontSize: 120, textColor: 'yellow' });

Audio tracks

audioTracks()

The active backend’s audio tracks. Returns [] for single-track sources or when no backend is mounted.

Returns: ReadonlyArray<AudioTrack>

interface AudioTrack {
  id: string;
  language?: string;
  label: string;
  channels?: number;
  default?: boolean;
}

audioTrack(idx?)

Read or write the active audio track.

Read: audioTrack() returns { index, track } or null when no explicit selection has been made.

Write: audioTrack(idx) selects the track at idx. Sets audioTrackMode to MANUAL.

Events emitted: audioTrack with { id: idx }; audioTrackState with { state: 'manual' }

Quality levels

qualityLevels(opts?)

The active backend’s quality levels. Returns [] for single-rendition sources.

opts.includeUnsupported: true returns every manifest level; the default filters to supported levels only.

Returns: ReadonlyArray<QualityLevel>

interface QualityLevel {
  bitrate: number;
  height?: number;
  width?: number;
  label: string;
  index: number;
  supported?: boolean;
  dynamicRange?: 'sdr' | 'hdr';
}

quality(idx?)

Read or write the active quality level.

Read: quality() returns { index, track } or 'auto' when adaptive bitrate selection is active.

Write: quality(idx) locks to a level; quality('auto') restores ABR. Sets qualityMode accordingly.

Events emitted: qualityState with { state: 'auto' | 'manual' }

// lock to 1080p (index varies per manifest)
player.quality(2);

// restore ABR
player.quality('auto');

Chapters

chapters()

Chapters for the active playlist item. Returns [] until the async chapter fetch settles, so subscribe to the chapters event for the ready signal.

Returns: ReadonlyArray<Chapter>

interface Chapter {
  index: number;
  start: number; // seconds
  end: number; // seconds
  title: string;
}

seekToChapter(idx, opts?)

Seek to the start of the chapter at idx. Out-of-range indexes no-op. Emits chapter after the seek.

nextChapter(opts?) / previousChapter(opts?)

Jump to the next or previous chapter. previousChapter applies a 10-second heuristic: if more than 10 s into the current chapter, jumps to that chapter’s start instead of the previous one.

chapter(idx?)

Read: returns the Chapter whose range contains time, or null.

Write: jump to the chapter at idx (same as seekToChapter(idx)).

See also

• Loading: resolveItemTrackUrls, sidecar track resolution
• Chapters: full chapter API reference
• Events Reference: subtitle, subtitleCue, audioTrack, chapters