@scarlett-player/hls 1.11.0 → 1.12.0

package/dist/live-metrics-CoYkWhl5.d.cts

@@ -0,0 +1,388 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * HLS Plugin Types
+ */
+
+/** HLS plugin configuration options */
+interface HLSPluginConfig {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Auto start loading when source is set */
+    autoStartLoad?: boolean;
+    /** Start position in seconds (-1 for default) */
+    startPosition?: number;
+    /**
+     * Enable low-latency HLS for live streams (default: false).
+     *
+     * Turning this on does more than set the hls.js flag: it also enables
+     * latency catch-up (`maxLiveSyncPlaybackRate`, which hls.js leaves at 1 and
+     * therefore disabled). Without it, LL-HLS parses and loads parts but latency
+     * settles wherever the buffer lands and is never pulled back. The retry
+     * budgets are deliberately left at their standard-live values; see
+     * `buildBaseHlsConfig()` for why widening them changes nothing a viewer
+     * could see.
+     *
+     * Opt-in, and it is a REQUEST: the manifest has to carry `EXT-X-PART` or
+     * advertise `CAN-BLOCK-RELOAD=YES` for low latency to actually happen. The
+     * `lowLatencyMode` state key and the `live:lowlatency` event report what the
+     * manifest supports, not what was requested here.
+     */
+    lowLatencyMode?: boolean;
+    /**
+     * Target latency for live streams in seconds, overriding the manifest's
+     * `PART-HOLD-BACK` / `HOLD-BACK`. Left unset, hls.js derives the target from
+     * the manifest, which is what a correctly packaged stream wants.
+     */
+    liveSyncDuration?: number;
+    /**
+     * Target latency expressed as a count of target durations (hls.js default:
+     * 3). Mutually exclusive with `liveSyncDuration`: hls.js THROWS on a config
+     * carrying both, so the plugin forwards one group only and logs which half
+     * it dropped.
+     */
+    liveSyncDurationCount?: number;
+    /**
+     * Maximum latency in seconds before the player seeks forward to catch up.
+     * Left unset, hls.js uses `liveMaxLatencyDurationCount`.
+     */
+    liveMaxLatencyDuration?: number;
+    /**
+     * Maximum latency as a count of target durations (hls.js default: Infinity,
+     * i.e. never force a catch-up seek).
+     */
+    liveMaxLatencyDurationCount?: number;
+    /**
+     * Playback rate ceiling used to catch up to the live edge (hls.js default:
+     * 1, which disables catch-up entirely).
+     *
+     * Defaults to 1.1 when `lowLatencyMode` is true and is left at hls.js's
+     * default otherwise, so standard live and VOD are unchanged. 1.1 recovers a
+     * second of drift in ten and the pitch shift is barely audible; 1.05 is
+     * safer and slower.
+     */
+    maxLiveSyncPlaybackRate?: number;
+    /**
+     * Report live streams with an Infinity duration rather than the length of
+     * the current sliding window (hls.js default: false).
+     */
+    liveDurationInfinity?: boolean;
+    /** Max buffer length in seconds */
+    maxBufferLength?: number;
+    /** Max max buffer length in seconds */
+    maxMaxBufferLength?: number;
+    /** Back buffer length in seconds for DVR */
+    backBufferLength?: number;
+    /** Enable worker for hls.js (better performance) */
+    enableWorker?: boolean;
+    /**
+     * Max network error retries before giving up (default: 3).
+     *
+     * Governs both playback branches: hls.js retries the load, and the native
+     * (Safari/iOS) path reloads the source and restores position.
+     */
+    maxNetworkRetries?: number;
+    /**
+     * Max media error retries before giving up (default: 2).
+     *
+     * Governs both playback branches: hls.js calls recoverMediaError(), and the
+     * native (Safari/iOS) path reloads the source and restores position.
+     */
+    maxMediaRetries?: number;
+    /** Cap quality to player element dimensions (default: true) */
+    capLevelToPlayerSize?: boolean;
+    /** Override initial bandwidth estimate in bits per second */
+    initialBandwidthEstimate?: number;
+    /** Base retry delay in milliseconds (default: 1000) */
+    retryDelayMs?: number;
+    /** Exponential backoff multiplier (default: 2) */
+    retryBackoffFactor?: number;
+    /**
+     * Watchdog for source loading in milliseconds (default: 30000, 0 disables).
+     * If the manifest has not parsed within this window the load fails with an
+     * error instead of leaving the viewer on a spinner forever.
+     */
+    loadTimeoutMs?: number;
+    /**
+     * Automatically attempt to reconnect after a fatal network/media error
+     * once the stream had been playing (default: true). Viewers should not
+     * have to press anything when a connection blip resolves itself.
+     */
+    autoReconnect?: boolean;
+    /** First auto-reconnect delay in milliseconds (default: 2000) */
+    reconnectBaseDelayMs?: number;
+    /** Cap for the auto-reconnect backoff in milliseconds (default: 30000) */
+    reconnectMaxDelayMs?: number;
+    /** Total window to keep auto-reconnecting in milliseconds (default: 300000 = 5 min) */
+    reconnectWindowMs?: number;
+    /**
+     * Validate every playlist response before it reaches the M3U8 parser
+     * (default: true). A live refresh that returns an error page, a
+     * master-only response, or an empty document becomes a normal network
+     * error (bounded retries, then reconnect, then the retry UI) instead of
+     * being indexed blindly.
+     */
+    validatePlaylists?: boolean;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+/** Quality level information */
+interface HLSQualityLevel {
+    /** Level index in hls.js */
+    index: number;
+    /** Video width */
+    width: number;
+    /** Video height */
+    height: number;
+    /** Bitrate in bits per second */
+    bitrate: number;
+    /** Human-readable label (e.g., "1080p") */
+    label: string;
+    /** Codec info */
+    codec?: string;
+}
+/** HLS error types */
+type HLSErrorType = 'network' | 'media' | 'mux' | 'other';
+/** HLS error details */
+interface HLSError {
+    type: HLSErrorType;
+    details: string;
+    fatal: boolean;
+    url?: string;
+    reason?: string;
+    response?: {
+        code: number;
+        text: string;
+    };
+}
+/** Live stream info */
+interface HLSLiveInfo {
+    /** Whether stream is live */
+    isLive: boolean;
+    /** Edge latency in seconds */
+    latency: number;
+    /** Target latency for low latency mode */
+    targetLatency: number;
+    /** Drift from live edge */
+    drift: number;
+    /** Position to seek to for live sync (seconds from start), when known */
+    liveSyncPosition?: number;
+    /**
+     * Whether the stream is EFFECTIVELY low latency - the manifest carries
+     * `EXT-X-PART` or advertises `CAN-BLOCK-RELOAD=YES` - rather than whether
+     * `lowLatencyMode` was requested in the plugin config.
+     */
+    lowLatency: boolean;
+}
+/** HLS Plugin interface extending base Plugin */
+interface IHLSPlugin extends Plugin<HLSPluginConfig> {
+    readonly id: 'hls-provider';
+    /** Check if this provider can play a source */
+    canPlay(src: string): boolean;
+    /** Load and play a source */
+    loadSource(src: string): Promise<void>;
+    /** Get current quality level index (-1 = auto) */
+    getCurrentLevel(): number;
+    /** Set quality level (-1 for auto) */
+    setLevel(index: number): void;
+    /** Get all available quality levels */
+    getLevels(): HLSQualityLevel[];
+    /** Get the raw hls.js instance (for advanced use) */
+    getHlsInstance(): unknown | null;
+    /** Check if using native HLS (Safari) */
+    isNativeHLS(): boolean;
+    /** Get live stream info */
+    getLiveInfo(): HLSLiveInfo | null;
+    /** Switch from hls.js to native HLS (for AirPlay) */
+    switchToNative(): Promise<void>;
+    /** Switch from native HLS back to hls.js */
+    switchToHlsJs(): Promise<void>;
+}
+/** Type guard for hls.js level */
+interface HlsLevel {
+    width: number;
+    height: number;
+    bitrate: number;
+    codecSet?: string;
+    name?: string;
+}
+/** Minimal hls.js interface for type safety */
+interface HlsInstance {
+    loadSource(src: string): void;
+    attachMedia(media: HTMLMediaElement): void;
+    detachMedia(): void;
+    startLoad(startPosition?: number): void;
+    stopLoad(): void;
+    recoverMediaError(): void;
+    destroy(): void;
+    on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
+    levels: HlsLevel[];
+    currentLevel: number;
+    autoLevelEnabled: boolean;
+    nextLevel: number;
+    loadLevel: number;
+    latency?: number;
+    targetLatency?: number;
+    drift?: number;
+    liveSyncPosition?: number;
+    bandwidthEstimate?: number;
+    media: HTMLMediaElement | null;
+    /** Alternate audio renditions declared by the manifest. */
+    audioTracks: HlsAudioTrack[];
+    /** Index into {@link audioTracks} of the rendition currently playing. */
+    audioTrack: number;
+}
+/**
+ * One alternate audio rendition, as hls.js reports it.
+ *
+ * Only the fields this plugin reads; hls.js attaches several more.
+ */
+interface HlsAudioTrack {
+    /** hls.js's own numeric id for the track. */
+    id?: number;
+    /** Human-readable NAME from the manifest, e.g. "Director Commentary". */
+    name?: string;
+    /** BCP 47 language tag from the manifest, when it declares one. */
+    lang?: string;
+    /** Whether the manifest marked this the default rendition. */
+    default?: boolean;
+    /** Rendition group the track belongs to. */
+    groupId?: string;
+}
+
+/**
+ * Live metrics: the single writer for the player's live/DVR state.
+ *
+ * Before this module, `liveLatency`, `liveEdge` and `seekableRange` had two
+ * writers with different definitions of "latency": `hlsLevelLoaded` computed
+ * an edge flag from the level details, and the `timeupdate` handler then
+ * recomputed it unconditionally from `video.seekable` as `latency < 10`. Under
+ * MSE the second source is wrong (`video.seekable.start(0)` stays 0 instead of
+ * following the sliding window), and at a 2-4s low-latency target `< 10s` is
+ * always true, so "GO LIVE" could never appear no matter how far a viewer
+ * drifted. Every write of those keys now goes through {@link applyLiveMetrics},
+ * so there is exactly one definition and no clobber.
+ *
+ * Latency truth differs by playback path:
+ *
+ * - **hls.js (MSE):** `hls.latency` is real wall-clock latency, computed from
+ *   `EXT-X-PROGRAM-DATE-TIME` drift where the manifest carries it, measured
+ *   against `hls.targetLatency` (which hls.js derives from `PART-HOLD-BACK` /
+ *   `HOLD-BACK`, or from `liveSyncDuration`* config when set).
+ * - **native (Safari/iOS):** there is no latency API. `video.seekable.end` is
+ *   the best available stand-in for the edge, so latency is the distance to it
+ *   — a buffer distance, not a measured latency. Treated as an approximation
+ *   throughout, and the edge threshold is deliberately loose unless a target
+ *   latency is known from a previous hls.js session on the same source.
+ */
+
+/**
+ * The level-details fields the live path reads, as hls.js reports them on
+ * `hlsLevelLoaded`.
+ *
+ * The LL-HLS members are the ones that decide whether a stream is *effectively*
+ * low latency: a host can set `lowLatencyMode: true` against a plain live
+ * manifest, and that must not produce an LL badge.
+ */
+interface HlsLevelDetails {
+    /** Whether the playlist is live (no EXT-X-ENDLIST) */
+    live?: boolean;
+    /** Total duration of the fragments in the playlist window, in seconds */
+    totalduration?: number;
+    /** EXT-X-TARGETDURATION, in seconds */
+    targetduration?: number;
+    /** Start of the sliding window, in seconds on the player timeline */
+    fragmentStart?: number;
+    /** End of the sliding window (live edge), in seconds on the player timeline */
+    edge?: number;
+    /** Fragments in the current playlist window */
+    fragments?: Array<{
+        start?: number;
+    }>;
+    /** LL-HLS: partial segments in the current window (EXT-X-PART) */
+    partList?: unknown[] | null;
+    /** LL-HLS: EXT-X-PART-INF PART-TARGET, in seconds */
+    partTarget?: number;
+    /** LL-HLS: EXT-X-SERVER-CONTROL CAN-BLOCK-RELOAD=YES */
+    canBlockReload?: boolean;
+    /** LL-HLS: EXT-X-SERVER-CONTROL PART-HOLD-BACK, in seconds */
+    partHoldBack?: number;
+    /** EXT-X-SERVER-CONTROL HOLD-BACK, in seconds */
+    holdBack?: number;
+}
+/** A snapshot of the live state of the stream, from one source of truth. */
+interface LiveMetrics {
+    /** Latency behind the live edge, in seconds */
+    latency: number;
+    /** Latency the stream is aiming for, in seconds */
+    targetLatency: number;
+    /** Whether the viewer counts as being AT the live edge (see below) */
+    atEdge: boolean;
+    /** DVR window on the player timeline, when it is known */
+    seekableRange: {
+        start: number;
+        end: number;
+    } | null;
+    /**
+     * Whether low latency is EFFECTIVE: the manifest carries `EXT-X-PART` or
+     * advertises `CAN-BLOCK-RELOAD=YES`, AND low latency was requested in the
+     * plugin config. Both halves matter. A host that sets `lowLatencyMode`
+     * against a plain live manifest gets no LL badge because the stream cannot
+     * deliver it; a host that leaves the flag off gets none against an LL
+     * manifest either, because hls.js will not load the parts.
+     */
+    lowLatency: boolean;
+}
+/** Where a {@link LiveMetrics} snapshot is measured from. */
+type LiveMetricsSource = {
+    /** hls.js (MSE) path: latency comes from hls.js itself */
+    kind: 'hls';
+    /** The live hls.js instance */
+    hls: HlsInstance;
+    /** Most recent level details, when one has been seen */
+    details?: HlsLevelDetails | null;
+    /**
+     * Whether low latency was requested in the plugin config. Defaults to
+     * true when omitted, so a caller that only has a manifest still gets the
+     * manifest's answer.
+     */
+    lowLatencyRequested?: boolean;
+} | {
+    /** Native path (Safari/iOS): latency is approximated from `seekable` */
+    kind: 'media';
+    /** The media element playing the live stream */
+    media: HTMLMediaElement;
+    /**
+     * Target latency carried over from an hls.js session on the same source
+     * (an AirPlay handoff). Absent on a stream that has only ever played
+     * natively, where nothing reveals the manifest's hold-back.
+     */
+    targetLatency?: number;
+    /**
+     * Whether to report the stream as effectively low latency. The HLS
+     * plugin never sets it on this path: native playback is a handoff, and
+     * nothing is loading parts any more.
+     */
+    lowLatency?: boolean;
+};
+/**
+ * Target latency assumed when nothing better is known. Matches hls.js's own
+ * fallback and the value `getLiveInfo()` reported before LL-HLS.
+ */
+declare const DEFAULT_TARGET_LATENCY = 3;
+/**
+ * Measure the live state of the stream from one source.
+ *
+ * Call it only for live content: for VOD the numbers are meaningless and the
+ * caller should not be writing live state at all.
+ *
+ * A viewer is AT the edge when `latency <= targetLatency + tolerance`, with the
+ * tolerance from {@link edgeTolerance}.
+ *
+ * @param source - hls.js instance (with its latest level details) or media element
+ * @returns The snapshot, or null when the source reveals nothing usable
+ */
+declare function computeLiveMetrics(source: LiveMetricsSource): LiveMetrics | null;
+
+export { DEFAULT_TARGET_LATENCY as D, type HLSPluginConfig as H, type IHLSPlugin as I, type LiveMetrics as L, type HLSQualityLevel as a, type HLSError as b, type HLSLiveInfo as c, computeLiveMetrics as d, type LiveMetricsSource as e, type HlsLevelDetails as f };