Exported types
All types are importable from the package root:
import type {
VideoPlaylistItem,
VideoPlayerConfig,
VideoEventMap,
IVideoPlayer,
VideoBackendFactory,
Stretching,
WatchProgress,
FontTrackRef,
SubtitleTrackRef,
AudioTrackRef,
ChapterRef,
SkipperData,
SkipperRange,
} from '@nomercy-entertainment/nomercy-video-player';
IVideoPlayer
interface IVideoPlayer<T extends BasePlaylistItem = VideoPlaylistItem>
extends IPlayer<VideoEventMap>
Typed contract for the video player’s public surface.
Use this to type plugin parameters and consumer functions rather than the concrete NMVideoPlayer class.
The interface is stable across patch versions.
import type { IVideoPlayer } from '@nomercy-entertainment/nomercy-video-player';
import { Plugin } from '@nomercy-entertainment/nomercy-player-core';
class MyPlugin extends Plugin<IVideoPlayer> {
override use(): void {
this.on('ready', () => {
this.player.play();
});
}
}
VideoPlaylistItem
See VideoPlaylistItem for full field documentation.
VideoPlayerConfig
Configuration passed to player.setup(config).
| Field | Type | Default | Description |
|---|---|---|---|
playlist | VideoPlaylistItem[] | string | none | Initial playlist or URL to fetch |
muted | boolean | false | Start muted |
autoPlay | boolean | false | Auto-play on setup |
controls | boolean | false | Show the native <video> controls element |
stretching | 'uniform' | 'fill' | 'exactfit' | 'none' | 'uniform' | Aspect ratio stretching mode |
playbackRates | number[] | [0.5, 0.75, 1, 1.25, 1.5, 2] (fixed) | Intended rate list; not yet read by the player (the list is currently fixed) |
preload | 'auto' | 'metadata' | 'none' | browser default | Intended <video> preload attribute; not yet read by the player |
disableMediaControls | boolean | false | Disable media key bindings (keyboard plugin) |
disableControls | boolean | false | Disable all controls |
backendFactory | VideoBackendFactory | none | Custom backend factory (advanced) |
defaultSubtitleLanguage | string | none | BCP-47 language tag to auto-select on load |
defaultAudioLanguage | string | none | BCP-47 language tag to auto-select on load |
defaultQuality | 'auto' | number | 'auto' | Default quality level index or 'auto' |
theaterDefault | boolean | false | Start in theater mode |
baseImageUrl | string | none | Base URL prepended to relative image paths on playlist items |
State enums
All state enums are exported from the package root:
PlayState
Returned by player.playState().
| Value | Description |
|---|---|
'idle' | No media loaded |
'loading' | Media is loading or buffering |
'playing' | Media is actively playing |
'paused' | Media is paused |
'stopped' | Playback stopped explicitly |
'error' | A fatal error occurred |
FullscreenState
| Value | Description |
|---|---|
'off' | Not in fullscreen |
'on' | In fullscreen |
PipState
| Value | Description |
|---|---|
'off' | Picture-in-Picture is inactive |
'on' | Picture-in-Picture is active |
TheaterState
| Value | Description |
|---|---|
'off' | Normal layout |
'on' | Theater (wide) mode active |
SubtitleState
| Value | Description |
|---|---|
'off' | No subtitle track active |
'on' | A subtitle track is active |
VolumeState
| Value | Description |
|---|---|
'unmuted' | Audio is playing |
'muted' | Audio is muted |
RepeatState
| Value | Description |
|---|---|
'off' | No repeat |
'all' | Repeat entire playlist |
'one' | Repeat current item |
ShuffleState
| Value | Description |
|---|---|
'off' | Sequential playback |
'on' | Shuffled playback |
Stretching
type Stretching = 'uniform' | 'fill' | 'exactfit' | 'none';
Controls how the video is scaled to fill the player container.
Used by aspectRatio() and cycleAspectRatio().
See Aspect Ratio.
VideoBackendFactory
type VideoBackendFactory = (
kind: VideoBackendKind,
config: VideoPlayerConfig<BasePlaylistItem>,
) => IVideoBackend;
Custom backend factory passed in VideoPlayerConfig.backendFactory.
Receives the resolved backend kind and the player config.
See Video Backend adapter.
VideoEventMap
The full map of events emitted by NMVideoPlayer.
Subscribe with player.on(event, listener).
| Event | Payload | Description |
|---|---|---|
'current' | { item: VideoPlaylistItem | undefined; index: number } | Active playlist item changed |
'quality:requested' | { level: number | 'auto' } | Quality level requested by consumer |
'chapter' | { index: number; title: string } | Emitted by seekToChapter / nextChapter / previousChapter (not on boundary crossing) |
'pip' | { active: boolean } | PiP state changed |
'theater' | { active: boolean } | Theater mode changed |
'fullscreen' | { active: boolean } | Fullscreen state changed |
'mute' | { muted: boolean } | Mute state changed |
'volume' | { level: number } | Volume level changed (0–100) |
'repeat' | { state: RepeatState } | Repeat mode changed |
'shuffle' | { state: ShuffleState } | Shuffle mode changed |
'aspectRatio' | { value: Stretching } | Aspect ratio changed |
'waiting' | void | Video element is buffering |
'canplay' | void | Enough data to begin playback |
'stalled' | void | Network stalled |
'levels' | { levels: QualityLevel[] } | HLS quality levels available |
'level-switched' | { level: number } | ABR switched quality level |
'audioTracks' | { tracks: AudioTrack[] } | Audio track list available |
'back' | void | Back button in the desktop UI was pressed |
Player Core base events (ready, time, duration, play, pause, ended, error, subtitle, subtitleCue, subtitleStyle, mediaReady, etc.) are inherited from BaseEventMap and documented at /nomercy-player-core/event-system.