Reference: Events

VideoEventMap<T> extends the kit’s BaseEventMap (transport, queue, volume, i18n, plugins, and the rest, unchanged for video). This page is only the events that exist because the medium is video, Playback State & Events is the narrative walkthrough of the same list.

Playback signals

waiting / canplay / stalled are video’s own. firstFrame is not, it lives on the kit’s BaseEventMap and fires identically for nomercy-music-player, listed here because it matters most in a video context.

Event	Payload	Fires when
`firstFrame`	`void`	The first decoded frame paints.
`waiting`	`void`	Backend buffering started.
`canplay`	`void`	Backend can resume playback.
`stalled`	`void`	Backend stalled fetching data.

Quality & tracks

Event	Payload	Fires when
`quality:requested`	`{ level: number \| 'auto' }`	A `quality()` call was made, before the backend confirms. Video-specific, fires ahead of the kit’s own `'level-switched'`.
`levels`	`{ levels: QualityLevel[] }`	HLS manifest parsed, the quality list is populated. May fire after `mediaReady`, subscribe here rather than reading `qualityLevels()` at ready time.
`audioTracks`	`{ tracks: AudioTrack[] }`	Audio-track list is populated.

Subtitles

These rows live on the kit’s BaseEventMap for shared-implementation reasons, but the methods that trigger them (subtitle(), subtitleStyle()) are video-only, nomercy-music-player doesn’t expose them, see Subtitles & Text Tracks.

Event	Payload	Fires when
`subtitleCue`	`SubtitleCueChange`	Every cue change, sidecar VTT or native text track alike, the single channel every subtitle renderer plugin subscribes to.
`subtitleStyle`	`SubtitleStyle`	`subtitleStyle(patch)` merged a style patch, the signal `SubtitleOverlayPlugin` repaints every active cue from.
`subtitle`	`{ track: number \| null }`	`subtitle(idx)` changed the active track, `null` when subtitles are off.
`beforeSubtitle` / `subtitlePrevented`	`BeforeEvent<{ track }>` / `{ reason, cause? }`	Fires before `subtitle(idx)` changes the active track, a listener can `preventDefault()` it.

Two more are genuinely video’s own, unlike the four rows above: KeyHandlerPlugin’s +/shift++/- bindings request a subtitle-size step. No shipped plugin listens, wire your own listener (or a custom overlay) to step subtitleStyle().fontSize.

Event	Payload	Fires when
`subtitle-size-up`	`void`	`+` / `shift++` requested a larger subtitle size.
`subtitle-size-down`	`void`	`-` requested a smaller subtitle size.

Display state

Event	Payload	Fires when
`pip`	`{ active: boolean }`	Picture-in-picture toggled and settled.
`theater`	`{ active: boolean }`	Theater mode toggled.
`fullscreen`	`{ active: boolean }`	Fullscreen toggled and settled.
`aspectRatio`	`{ value: Stretching }`	`aspectRatio()` or `cycleAspectRatio()` changed the object-fit mode.
`videoRect`	`{ rect: VideoRect \| null }`	The displayed content rectangle changed, driven by `mediaReady`, `duration`, `fullscreen`, and a `ResizeObserver` on the container and video element. Overlay plugins (subtitles, letterbox borders, click-to-seek layers) align to this instead of maintaining their own observer.

Segments

Event	Payload	Fires when
`segmentBoundary`	`{ startSec: number; endSec: number; onEnd: SegmentEndBehaviour }`	A `playSegment()` window’s `endSec` is reached, always fires regardless of `onEnd` mode.

Event	Payload	Fires when
`display-message`	`{ text: string; ms?: number }`	An OSD toast is requested. The active UI plugin (`DesktopUiPlugin`, `TvKeyHandlerPlugin`) renders it, the player itself has no OSD chrome.
`remove-message`	`undefined`	Dismiss the active toast before its duration elapses.
`back`	`void`	Navigation intent from a UI plugin’s back button. The player has no navigation stack, a consumer listener handles routing. Visible on the UI only when at least one listener is registered.
`close`	`void`	Dismissal intent from a UI plugin’s close button. Same visibility rule as `back`.
`cast`	`void`	Click intent from `DesktopUiPlugin`’s top-bar cast button (opt-in via `buttons: { cast: true }`, default off, see Plugin: Desktop UI). The player has no opinion on device selection or handoff, a consumer listener opens its own device picker. Unlike `back`/`close`, visibility does not depend on a listener being registered.

Next steps

Reference: Types: VideoPlaylistItem, the enums these payloads reference, and every other domain type.