import type { AudioTrack, QualityLevel, SubtitleTrack } from '@nomercy-entertainment/nomercy-player-core'; import type { HtmlPreloadMode } from '../../types.js'; import type { BackendEventPayload, BackendState, IVideoBackend } from './IVideoBackend.js'; import { MediaElementBackend } from '@nomercy-entertainment/nomercy-player-core'; /** * Default video backend. Wraps an `` for transport. * * HLS support: native pass-through when `canPlayType` reports support * (Safari / iOS), otherwise dynamically imports `hls.js` (peer dep — not * bundled; IIFE build externalises it as `window.Hls`, ESM build resolves * it from the consumer's node_modules) and attaches it. MSE / WebCodecs * backends ship later. */ export declare class Html5VideoBackend extends MediaElementBackend implements IVideoBackend { readonly kind: "html5"; private hls; private currentUrl; private _state; private _hadError; private _ended; /** * Listener attached to the active `TextTrack` so we can detach on track * switch / dispose without rebuilding the rest of the listeners map. */ private cueChangeHandler; /** * Codec → supported flag. Populated asynchronously after MANIFEST_PARSED. * Keys are CODECS attribute strings from HLS level attributes. */ private _capabilityCache; /** * Retry count for the current fatal network-error sequence. Reset on * successful playback resume. */ private _netRetryCount; /** * Timestamp (ms) when the first media-error recovery was attempted. * Used to detect a second media error within the 5-second escalation window. */ private _mediaRecoveryStartMs; /** Timer handle for exponential back-off retries. Cleared on unload/dispose. */ private _retryTimer; private _sourceNode?; private _sourceCtx?; private _analyserNode?; private _outputGain?; /** * Dynamic-range constraint strategy for HLS.js ABR. * * On manifests that carry both SDR and HDR (PQ/HLG) level variants — * e.g. Cosmos Laundromat (7 resolution tiers × SDR + HDR = 14 levels) — * HLS.js ABR is oblivious to display capability and can freely pick a PQ * variant on an SDR display (colours look washed out). This block wires * three responses: * * 1. Constraint on load — after MANIFEST_PARSED, if the display is SDR * the highest-SDR-level index is stored in `autoLevelCapping` so ABR * never selects above it. For interleaved manifests (HDR index < SDR * index at the same resolution) `nextLevel` force-switches away from * any currently-playing HDR variant to its SDR peer. * * 2. Live display flip — matchMedia `change` listener (wired in the * constructor, torn down in dispose). On SDR→HDR: lift the cap and * optionally prefer a PQ peer at the same resolution. On HDR→SDR: * cap + force-switch the playing level if it is a PQ variant. * * 3. Audio continuity — switching levels via `nextLevel` is seamless * when the new level shares the same audio group ID, which HLS.js * ensures for well-formed manifests (same resolution tier). No extra * audio continuity guard is needed here. */ /** Whether the active display reported HDR capability at the last check. */ private _displayHdr; /** * Per-level SDR/HDR classification. Populated after each MANIFEST_PARSED. * Index matches `hls.levels[i]`. `true` = HDR (PQ or HLG), `false` = SDR. */ private _levelIsHdr; /** * matchMedia query for display HDR capability. Tracked so we can remove * the listener on dispose without leaking the closure. */ private _hdrMql; /** * Bound listener for `_hdrMql` change events. Stored so we can call * `removeEventListener` with the same reference on dispose. */ private _hdrMqlListener; constructor(container: HTMLElement); /** * `startTime` is consumed natively (declared via `canStartAt`): the hls.js * path maps it to `startPosition` so the FIRST fragment fetched is the one * containing the offset — fragment 0 is never requested. The native / * progressive path sets `element.currentTime` once metadata arrives. */ readonly canStartAt: boolean; load(url: string, opts?: { preload?: HtmlPreloadMode; startTime?: number; }): Promise; unload(): void; dispose(): void; private _teardownAudioGraph; buffered(): number; videoWidth(): number; videoHeight(): number; audioTracks(): AudioTrack[]; setAudioTrack(idx: number): void; subtitleTracks(): SubtitleTrack[]; setSubtitleTrack(idx: number | null): void; /** * Match the kit-facing subtitle index back to the underlying * `TextTrack` instance. * * For HLS-managed tracks (`hls.subtitleTracks[idx]`), match against * `element.textTracks` by `language + label`. The catch: HLS streams * with CEA-608 / CEA-708 closed captions embedded in the MPEG-TS * video (e.g. Apple's bipbop-advanced) get auto-extracted by HLS.js * into a `kind: 'captions'` track that often shares the same * `language` and `label` as the WebVTT subtitle track. Match-by- * lang+label alone ambiguously picks the FIRST one — usually the * CEA captions, which are NOT the same as the WebVTT track the * user selected. Prefer `kind: 'subtitles'` (WebVTT) over * `kind: 'captions'` (CEA) when both match. * * Native (non-HLS) sources index the textTrack list directly. */ private resolveSubtitleTextTrack; private disableAllSubtitleTextTracks; private detachActiveTextTrack; /** * Read the active cues off a `TextTrack` and emit them through the * backend's `subtitleCue` channel. Each `VTTCue` is normalised into * the backend-agnostic `SubtitleCue` shape so renderers don't have * to know whether the source was an HLS-fed VTT or a native track. */ private emitEmptySubtitleCue; private emitActiveCues; qualityLevels(): QualityLevel[]; qualityLevels(opts: { includeUnsupported: true; }): QualityLevel[]; private _probeCodecCapabilities; setQuality(idx: number | 'auto'): void; currentLevel(): number; /** * Live throughput estimate in bits per second, read straight off the * active hls.js instance's own EWMA estimator. `0` when no HLS instance * is bound (native/progressive playback, or before `load()` has attached * one) — the kit's public `bandwidth()` treats `0` as "no estimate yet", * so this never reports a stale or fabricated number. */ bandwidthEstimate(): number; state(): BackendState; outputProtectionState(): 'unrestricted' | 'restricted' | 'unsupported'; /** * Returns the tail of the backend's Web Audio graph (a `GainNode` whose * output flows to `ctx.destination` by default). Mirrors * `AudioElementBackend.outputNode` exactly. The graph is built lazily on * first call so backends that are never tapped pay zero Web Audio cost and * the autoplay policy is never triggered ahead of user interaction. * * `AudioGraphPlugin` disconnects the baseline `outputGain → destination` * routing and rewires through its effect chain on `use()`. */ outputNode(ctx: AudioContext): AudioNode; /** * Returns the raw `MediaElementAudioSourceNode` — the pre-volume source — * so that `AudioGraphPlugin` can tap the `AnalyserNode` upstream of the * volume fader and produce volume-independent spectrum/FFT magnitudes. */ analysisNode(ctx: AudioContext): AudioNode; /** * Build the minimal Web Audio signal chain lazily: * `MediaElementAudioSourceNode → AnalyserNode → GainNode → destination`. * * Idempotent for the same `ctx`. If called with a different context the old * graph is disconnected and rebuilt (the consumer swapped AudioContext). * The graph mirrors `AudioElementBackend.ensureSourceGraph` so `AudioGraphPlugin` * can treat both backends identically. */ private _ensureAudioGraph; /** * Wire video-specific DOM events onto the element, tracking each handler * in `this.domHandlers` (inherited from `MediaElementBackend`) so * `detachDomBridges()` removes them cleanly on dispose. * * Video adds `resize`, `emptied`, `loadeddata`, and error-code mapping * on top of the standard 13 events handled by `attachDomBridgesTo`. * Rather than calling the base helper (which would add state-mutation * handlers appropriate for the audio path), video wires its own full * event set here to keep the custom `ended`/`error` side-effects intact. */ private wireElementEvents; /** Reset all recovery counters. Call on successful playback resume or unload. */ private _resetRecoveryState; /** * Escalate a fatal HLS error to a player-level error event. * * @param details - `HlsErrorData.details` string from hls.js * @param message - Human-readable summary for the error payload */ private _escalateHlsError; /** * Subscribe to `Hls.Events.ERROR` on the current `this.hls` instance. * Must be called after every HLS instance creation (including the CEA * fallback reload) because hls.js event listeners are per-instance. * * Decision tree per hls.js error semantics: * - Non-fatal → emit `stream:error` with `fatal: false`, no escalation. * - Fatal NETWORK → retry `hls.startLoad()` up to 3× with exponential * back-off (1 s, 2 s, 4 s). If exhausted, escalate. * - Fatal MEDIA → call `hls.recoverMediaError()`. If a second media * error fires within 5 s, escalate. * - Fatal MUX / other → destroy + reload via `load()`. If that fails, escalate. * * @param Hls - The hls.js constructor (carries static `Events` + `ErrorTypes`) * @param url - The manifest URL, needed for MUX destroy-reload. */ private _attachHlsErrorHandler; /** * Emit `levels` and `audioTracks` backend events from the current HLS * instance's live lists. Called after every `MANIFEST_PARSED` event so * overlay plugins can update button visibility without polling. * * Also builds the per-level HDR classification table and immediately * applies the dynamic-range ABR constraint for the current display. */ private _emitHlsTrackLists; /** Wire the `matchMedia('(dynamic-range: high)')` change listener once. */ private _wireHdrMatchMedia; /** Remove the matchMedia listener. Called from `dispose()`. */ private _teardownHdrMatchMedia; /** * Build `_levelIsHdr[]` from the current HLS level list. * A level is HDR when its VIDEO-RANGE attribute is `PQ` or `HLG`. */ private _classifyHdrLevels; /** * Constrain HLS.js ABR to the display's dynamic-range capability. * * SDR display (`displayHdr = false`): * - Sets `hls.autoLevelCapping` to the highest SDR level index so the * ABR algorithm never auto-selects above it. For interleaved manifests * where some HDR level indices sit below some SDR level indices, * `autoLevelCapping` alone is insufficient — we also force a `nextLevel` * switch away from any currently-playing HDR variant to its nearest SDR * peer at the same (or next-lower) resolution. * - Emits a fresh `levels` event so overlay plugins can hide HDR rows. * * HDR display (`displayHdr = true`): * - Lifts `autoLevelCapping` to `-1` (uncapped). ABR is free to select * HDR variants. If the current level is SDR and an HDR peer exists at * the same resolution, prefer it by setting `nextLevel` (soft switch — * the next fragment boundary picks it up; no stutter). * - Emits a fresh `levels` event so overlay plugins can reveal HDR rows. */ private _applyHdrConstraint; /** Called by the matchMedia listener when the display's HDR capability changes. */ private _onDisplayHdrChange; /** * Subscribe to HLS level-change signals on the current `this.hls` instance * and forward them as the backend's `level-switched` event. Must be called * after every HLS instance creation alongside `_attachHlsErrorHandler`. * * Listens to two HLS events for robustness: * - `LEVEL_SWITCHED` — the "official" level change. Fires reliably for * the initial pick and explicit setQuality() calls, but can go silent * for ABR-driven sub-switches that happen at fragment boundaries. * - `FRAG_CHANGED` — every fragment swap. Carries `frag.level`, so when * a fragment lands on a different level than the previous one, that's * effectively a level switch. Catches the cases LEVEL_SWITCHED misses. * * Both paths dedupe through `lastLevel` so consumers never see two * `level-switched` emissions for the same actual level. */ private _attachHlsLevelSwitchedHandler; private waitForLoadedMetadata; }