@scarlett-player/hls 1.11.0 → 1.12.0

package/README.md

@@ -25,6 +25,8 @@ const player = await createPlayer({
 
 - Adaptive bitrate streaming with quality level selection
 - Live stream support with DVR
+- Low-latency HLS (LL-HLS): part loading, latency catch-up, and live metrics
+  reported through player state
 - Native Safari HLS fallback (and hls.js lazy loading everywhere else)
 - Self-healing error recovery: bounded retries with jittered backoff,
   auto-reconnect after mid-playback failures (VOD resumes at position, live
@@ -55,9 +57,18 @@ createHLSPlugin({
   // Loading
   autoStartLoad: true,
   startPosition: -1,
-  lowLatencyMode: false,
   loadTimeoutMs: 30000,         // Load watchdog; 0 disables
 
+  // Live / low latency (see below). Every key here except lowLatencyMode is
+  // left to hls.js unless you set it - none is ever passed as undefined.
+  lowLatencyMode: false,
+  liveSyncDuration: undefined,          // Target latency in seconds
+  liveSyncDurationCount: undefined,     // ...or as a count of target durations
+  liveMaxLatencyDuration: undefined,    // Seek forward past this latency
+  liveMaxLatencyDurationCount: undefined,
+  maxLiveSyncPlaybackRate: undefined,   // Defaults to 1.1 when lowLatencyMode
+  liveDurationInfinity: undefined,      // Report live duration as Infinity
+
   // Error recovery
   maxNetworkRetries: 3,
   maxMediaRetries: 2,
@@ -73,6 +84,69 @@ createHLSPlugin({
 });
 ```
 
+## Low-Latency HLS
+
+`lowLatencyMode` is off by default and opt-in, so upgrading changes nothing for
+an existing consumer. Turning it on does more than set the hls.js flag:
+
+```typescript
+createHLSPlugin({ lowLatencyMode: true });
+```
+
+- hls.js loads `EXT-X-PART` parts and issues blocking playlist reloads.
+- **Latency catch-up is enabled.** hls.js ships `maxLiveSyncPlaybackRate: 1`,
+  which disables catch-up entirely, so LL-HLS would otherwise parse and load
+  parts and then let latency settle wherever the buffer landed and never pull
+  it back. The plugin defaults it to `1.1` when (and only when) low latency is
+  requested. Override it - `1.05` is gentler and slower to recover.
+- `liveSyncDuration` / `liveSyncDurationCount` override the target latency the
+  manifest asks for; `liveMaxLatencyDuration` / `liveMaxLatencyDurationCount`
+  set the latency at which the player seeks forward instead of speeding up.
+
+**The manifest has to support it.** Low latency needs
+`#EXT-X-SERVER-CONTROL:CAN-BLOCK-RELOAD=YES,PART-HOLD-BACK=<n>` and
+`#EXT-X-PART` (declared with `#EXT-X-PART-INF:PART-TARGET=<n>`). Setting the
+flag against a plain live playlist changes nothing but the config.
+
+### What the player reports
+
+| Key | Meaning |
+|---|---|
+| `live` | The playlist has no `EXT-X-ENDLIST` |
+| `liveLatency` | Seconds behind the live edge |
+| `liveEdge` | `latency <= targetLatency + max(1.5, partTarget ?? targetduration / 2)` |
+| `seekableRange` | The DVR window, from the playlist rather than `video.seekable` |
+| `lowLatencyMode` | Low latency is EFFECTIVE - see below |
+
+Each has a matching event: `live:latency`, `live:edgechange`,
+`live:seekablerange`, `live:lowlatency`. All four fire only on change.
+
+`lowLatencyMode` reports effect, not intent: it is true only when the manifest
+actually carries parts (or advertises blocking reloads) **and** the config
+requested low latency. A host that sets the flag against a plain live manifest
+gets no LL badge, and neither does an LL manifest played without the flag,
+because hls.js will not load its parts either way.
+
+`getLiveInfo()` returns the same truth from the provider directly:
+
+```typescript
+const provider = player.getPlugin('hls-provider');
+provider.getLiveInfo();
+// { isLive: true, latency: 1.53, targetLatency: 1.5, drift: 1.0,
+//   liveSyncPosition: 24.55, lowLatency: true }
+```
+
+On native Safari HLS there is no latency API, so `latency` is the distance to
+`video.seekable.end` - a buffer distance, not a measured latency - and the edge
+threshold stays deliberately loose. Treat those numbers as an approximation.
+
+### Rejoining the live edge
+
+Call `player.seekToLive()`, or emit `live:seektolive` from a control. Both land
+on the provider's `liveSyncPosition` before falling back to the end of the
+seekable range. Under low latency that distinction matters: the end of the
+seekable range is past the last loaded part, and seeking there stalls.
+
 ## Error Recovery
 
 Recoverable errors retry with jittered exponential backoff; the retry budget

package/dist/{chunk-NVPSLRJY.js → chunk-47MU7IVX.js}

@@ -7,6 +7,107 @@ var __export = (target, all) => {
 // src/sanitize-url.ts
 import { sanitizeUrl } from "@scarlett-player/core";
 
+// src/live-metrics.ts
+var DEFAULT_TARGET_LATENCY = 3;
+var MIN_EDGE_TOLERANCE = 1.5;
+var NATIVE_EDGE_TOLERANCE = 7;
+var EPSILON = 0.05;
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function rangeFromDetails(details) {
+  if (!details) return null;
+  const start = finite(details.fragmentStart) ?? finite(details.fragments?.[0]?.start) ?? 0;
+  const total = finite(details.totalduration);
+  const end = finite(details.edge) ?? (total === null ? null : start + total);
+  if (end === null) return null;
+  return { start, end };
+}
+function rangeFromMedia(media) {
+  const seekable = media?.seekable;
+  if (!seekable || seekable.length === 0) return null;
+  const start = seekable.start(0);
+  const end = seekable.end(seekable.length - 1);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  return { start, end };
+}
+function targetFromDetails(details) {
+  if (!details) return null;
+  const targetduration = finite(details.targetduration);
+  return finite(details.partHoldBack) ?? finite(details.holdBack) ?? (targetduration !== null ? targetduration * 3 : null);
+}
+function edgeTolerance(details, targetLatency) {
+  const targetduration = finite(details?.targetduration);
+  const half = targetduration !== null ? targetduration / 2 : targetLatency / 2;
+  return Math.max(MIN_EDGE_TOLERANCE, finite(details?.partTarget) ?? half);
+}
+function computeLiveMetrics(source) {
+  if (source.kind === "hls") {
+    const { hls, details } = source;
+    const media2 = hls.media;
+    const seekableRange2 = rangeFromDetails(details) ?? rangeFromMedia(media2);
+    const targetLatency2 = finite(hls.targetLatency) ?? targetFromDetails(details) ?? DEFAULT_TARGET_LATENCY;
+    const latency2 = finite(hls.latency) ?? (seekableRange2 && media2 ? Math.max(0, seekableRange2.end - media2.currentTime) : null);
+    if (latency2 === null && seekableRange2 === null) return null;
+    const resolvedLatency = latency2 ?? 0;
+    return {
+      latency: resolvedLatency,
+      targetLatency: targetLatency2,
+      atEdge: resolvedLatency <= targetLatency2 + edgeTolerance(details, targetLatency2),
+      seekableRange: seekableRange2,
+      // Effective LL, not requested LL: the manifest has to carry parts or
+      // advertise blocking reloads, AND the host has to have asked for it.
+      lowLatency: source.lowLatencyRequested !== false && (!!details?.partList?.length || details?.canBlockReload === true)
+    };
+  }
+  const { media } = source;
+  const seekableRange = rangeFromMedia(media);
+  if (!seekableRange) return null;
+  const targetLatency = source.targetLatency ?? DEFAULT_TARGET_LATENCY;
+  const tolerance = source.targetLatency === void 0 ? NATIVE_EDGE_TOLERANCE : Math.max(MIN_EDGE_TOLERANCE, source.targetLatency / 2);
+  const latency = Math.max(0, seekableRange.end - media.currentTime);
+  return {
+    latency,
+    targetLatency,
+    atEdge: latency <= targetLatency + tolerance,
+    seekableRange,
+    lowLatency: source.lowLatency === true
+  };
+}
+function applyLiveMetrics(api, metrics) {
+  if (!metrics) return;
+  const previousLatency = api.getState("liveLatency");
+  if (Math.abs(previousLatency - metrics.latency) > EPSILON) {
+    api.setState("liveLatency", metrics.latency);
+    api.emit("live:latency", { latency: metrics.latency });
+  }
+  if (api.getState("liveEdge") !== metrics.atEdge) {
+    api.setState("liveEdge", metrics.atEdge);
+    api.emit("live:edgechange", { atEdge: metrics.atEdge });
+  }
+  const range = metrics.seekableRange;
+  if (range) {
+    const previous = api.getState("seekableRange");
+    if (!previous || Math.abs(previous.start - range.start) > EPSILON || Math.abs(previous.end - range.end) > EPSILON) {
+      api.setState("seekableRange", { start: range.start, end: range.end });
+      api.emit("live:seekablerange", { start: range.start, end: range.end });
+    }
+  }
+  if (api.getState("lowLatencyMode") !== metrics.lowLatency) {
+    api.setState("lowLatencyMode", metrics.lowLatency);
+    api.emit("live:lowlatency", { enabled: metrics.lowLatency });
+  }
+}
+function resetLiveMetrics(api) {
+  if (api.getState("lowLatencyMode")) {
+    api.setState("lowLatencyMode", false);
+    api.emit("live:lowlatency", { enabled: false });
+  }
+  api.setState("liveLatency", 0);
+  api.setState("liveEdge", false);
+  api.setState("seekableRange", null);
+}
+
 // src/create-hls-plugin.ts
 import { ErrorCode } from "@scarlett-player/core";
 
@@ -206,16 +307,18 @@ function setupHlsEventHandlers(hls, api, callbacks) {
     if (data.details?.live !== void 0) {
       api.setState("live", data.details.live);
       if (data.details.live) {
-        const details = data.details;
-        const start = details.fragmentStart ?? (details.fragments?.[0]?.start ?? 0);
-        const end = details.edge ?? details.totalduration ?? 0;
-        api.setState("seekableRange", { start, end });
-        const video = hls.media;
-        if (video) {
-          const latency = Math.max(0, end - video.currentTime);
-          api.setState("liveLatency", latency);
-          api.setState("liveEdge", latency < (details.targetduration ?? 3) * 3);
-        }
+        callbacks.onLevelDetails?.(data.details);
+        applyLiveMetrics(
+          api,
+          computeLiveMetrics({
+            kind: "hls",
+            hls,
+            details: data.details,
+            lowLatencyRequested: callbacks.isLowLatencyRequested?.() ?? true
+          })
+        );
+      } else {
+        resetLiveMetrics(api);
       }
       callbacks.onLiveUpdate?.();
     }
@@ -255,7 +358,7 @@ function setupHlsEventHandlers(hls, api, callbacks) {
     api.setState("currentAudioTrack", null);
   };
 }
-function setupVideoEventHandlers(video, api) {
+function setupVideoEventHandlers(video, api, getLiveMetrics) {
   const handlers = [];
   const addHandler = (event, handler) => {
     video.addEventListener(event, handler);
@@ -292,15 +395,11 @@ function setupVideoEventHandlers(video, api) {
   addHandler("timeupdate", () => {
     api.setState("currentTime", video.currentTime);
     api.emit("playback:timeupdate", { currentTime: video.currentTime });
-    if (video.seekable && video.seekable.length > 0) {
-      if (api.getState("live") || !Number.isFinite(video.duration)) {
-        const start = video.seekable.start(0);
-        const end = video.seekable.end(video.seekable.length - 1);
-        api.setState("seekableRange", { start, end });
-        const latency = Math.max(0, end - video.currentTime);
-        api.setState("liveEdge", latency < 10);
-        api.setState("liveLatency", latency);
-      }
+    if (api.getState("live") || !Number.isFinite(video.duration)) {
+      applyLiveMetrics(
+        api,
+        getLiveMetrics ? getLiveMetrics() : computeLiveMetrics({ kind: "media", media: video })
+      );
     }
   });
   addHandler("durationchange", () => {
@@ -448,7 +547,7 @@ function createValidatingPlaylistLoader(Hls) {
 }
 
 // src/version.ts
-var PKG_VERSION = true ? "1.11.0" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.12.0" : "0.0.0-dev";
 
 // src/create-hls-plugin.ts
 var DEFAULT_CONFIG = {
@@ -476,6 +575,7 @@ var DEFAULT_CONFIG = {
   // Never index a malformed live playlist refresh blindly
   validatePlaylists: true
 };
+var LL_CATCH_UP_PLAYBACK_RATE = 1.1;
 var MANIFEST_PHASE_ERRORS = [
   "manifestLoadError",
   "manifestLoadTimeOut",
@@ -491,6 +591,9 @@ function createHLSPluginWith(loader, variant, config) {
   let cleanupHlsEvents = null;
   let cleanupVideoEvents = null;
   let isAutoQuality = true;
+  let lastLevelDetails = null;
+  let lastLiveMetrics = null;
+  let lastKnownTargetLatency = null;
   let loadSession = 0;
   let abortPendingLoad = null;
   let networkRetryCount = 0;
@@ -513,6 +616,24 @@ function createHLSPluginWith(loader, variant, config) {
   let stallWatchdogTimer = null;
   let lastStallCheckTime = 0;
   let lastStallCheckPosition = 0;
+  const readLiveMetrics = () => {
+    const metrics = hls && !isNative ? computeLiveMetrics({
+      kind: "hls",
+      hls,
+      details: lastLevelDetails,
+      lowLatencyRequested: mergedConfig.lowLatencyMode === true
+    }) : video ? computeLiveMetrics({
+      kind: "media",
+      media: video,
+      targetLatency: lastKnownTargetLatency ?? void 0,
+      lowLatency: lastLiveMetrics?.lowLatency
+    }) : null;
+    if (metrics) {
+      lastLiveMetrics = metrics;
+      if (hls && !isNative) lastKnownTargetLatency = metrics.targetLatency;
+    }
+    return metrics;
+  };
   const applyPoster = () => {
     if (!video) return;
     video.poster = api?.getState("poster") || "";
@@ -562,6 +683,10 @@ function createHLSPluginWith(loader, variant, config) {
     mediaRetryCount = 0;
     errorCount = 0;
     errorWindowStart = 0;
+    lastLevelDetails = null;
+    lastLiveMetrics = null;
+    lastKnownTargetLatency = null;
+    if (api) resetLiveMetrics(api);
   };
   const buildHlsConfig = () => {
     const config2 = buildBaseHlsConfig();
@@ -573,27 +698,58 @@ function createHLSPluginWith(loader, variant, config) {
     }
     return config2;
   };
-  const buildBaseHlsConfig = () => ({
-    debug: mergedConfig.debug,
-    autoStartLoad: mergedConfig.autoStartLoad,
-    startPosition: mergedConfig.startPosition,
-    startLevel: -1,
-    // Auto quality selection (ABR)
-    abrEwmaDefaultEstimate: getInitialBandwidthEstimate(mergedConfig.initialBandwidthEstimate),
-    lowLatencyMode: mergedConfig.lowLatencyMode,
-    maxBufferLength: mergedConfig.maxBufferLength,
-    maxMaxBufferLength: mergedConfig.maxMaxBufferLength,
-    backBufferLength: mergedConfig.backBufferLength,
-    enableWorker: mergedConfig.enableWorker,
-    capLevelToPlayerSize: mergedConfig.capLevelToPlayerSize,
-    // Minimize hls.js internal retries - we handle retries ourselves
-    fragLoadingMaxRetry: 1,
-    manifestLoadingMaxRetry: 1,
-    levelLoadingMaxRetry: 1,
-    fragLoadingRetryDelay: 500,
-    manifestLoadingRetryDelay: 500,
-    levelLoadingRetryDelay: 500
-  });
+  const buildLiveHlsConfig = () => {
+    const live = {};
+    const set = (key, value) => {
+      if (value !== void 0) live[key] = value;
+    };
+    const syncDuration = mergedConfig.liveSyncDuration;
+    const syncCount = mergedConfig.liveSyncDurationCount;
+    const maxDuration = mergedConfig.liveMaxLatencyDuration;
+    const maxCount = mergedConfig.liveMaxLatencyDurationCount;
+    const mixed = (syncDuration !== void 0 || maxDuration !== void 0) && (syncCount !== void 0 || maxCount !== void 0);
+    const dropCount = mixed && syncDuration !== void 0;
+    const dropDuration = mixed && !dropCount;
+    if (mixed) {
+      api?.logger.warn(
+        `Ignoring ${dropCount ? "liveSyncDurationCount/liveMaxLatencyDurationCount" : "liveSyncDuration/liveMaxLatencyDuration"}: hls.js rejects a config mixing seconds-based and count-based live latency options`
+      );
+    }
+    set("liveSyncDuration", dropDuration ? void 0 : syncDuration);
+    set("liveSyncDurationCount", dropCount ? void 0 : syncCount);
+    set("liveMaxLatencyDuration", dropDuration ? void 0 : maxDuration);
+    set("liveMaxLatencyDurationCount", dropCount ? void 0 : maxCount);
+    set("liveDurationInfinity", mergedConfig.liveDurationInfinity);
+    set(
+      "maxLiveSyncPlaybackRate",
+      mergedConfig.maxLiveSyncPlaybackRate ?? (mergedConfig.lowLatencyMode === true ? LL_CATCH_UP_PLAYBACK_RATE : void 0)
+    );
+    return live;
+  };
+  const buildBaseHlsConfig = () => {
+    return {
+      debug: mergedConfig.debug,
+      autoStartLoad: mergedConfig.autoStartLoad,
+      startPosition: mergedConfig.startPosition,
+      startLevel: -1,
+      // Auto quality selection (ABR)
+      abrEwmaDefaultEstimate: getInitialBandwidthEstimate(mergedConfig.initialBandwidthEstimate),
+      lowLatencyMode: mergedConfig.lowLatencyMode,
+      maxBufferLength: mergedConfig.maxBufferLength,
+      maxMaxBufferLength: mergedConfig.maxMaxBufferLength,
+      backBufferLength: mergedConfig.backBufferLength,
+      enableWorker: mergedConfig.enableWorker,
+      capLevelToPlayerSize: mergedConfig.capLevelToPlayerSize,
+      // Minimize hls.js internal retries - we handle retries ourselves
+      fragLoadingMaxRetry: 1,
+      manifestLoadingMaxRetry: 1,
+      levelLoadingMaxRetry: 1,
+      fragLoadingRetryDelay: 500,
+      manifestLoadingRetryDelay: 500,
+      levelLoadingRetryDelay: 500,
+      ...buildLiveHlsConfig()
+    };
+  };
   const getRetryDelay = (retryCount) => {
     const baseDelay = mergedConfig.retryDelayMs ?? 1e3;
     const backoffFactor = mergedConfig.retryBackoffFactor ?? 2;
@@ -790,7 +946,7 @@ function createHLSPluginWith(loader, variant, config) {
     const videoEl = getOrCreateVideo();
     isNative = true;
     if (api) {
-      cleanupVideoEvents = setupVideoEventHandlers(videoEl, api);
+      cleanupVideoEvents = setupVideoEventHandlers(videoEl, api, readLiveMetrics);
     }
     return new Promise((resolve, reject) => {
       let watchdog = null;
@@ -883,7 +1039,7 @@ function createHLSPluginWith(loader, variant, config) {
     isNative = false;
     hls = loader.createHlsInstance(buildHlsConfig());
     if (api) {
-      cleanupVideoEvents = setupVideoEventHandlers(videoEl, api);
+      cleanupVideoEvents = setupVideoEventHandlers(videoEl, api, readLiveMetrics);
     }
     return new Promise((resolve, reject) => {
       if (!hls || !api) {
@@ -925,6 +1081,12 @@ function createHLSPluginWith(loader, variant, config) {
         },
         onLevelSwitched: () => {
         },
+        onLevelDetails: (details) => {
+          if (session !== loadSession) return;
+          lastLevelDetails = details;
+          readLiveMetrics();
+        },
+        isLowLatencyRequested: () => mergedConfig.lowLatencyMode === true,
         onError: (error) => {
           if (session !== loadSession) return;
           const terminal = handleHlsError(error);
@@ -1362,25 +1524,45 @@ function createHLSPluginWith(loader, variant, config) {
     isNativeHLS() {
       return isNative;
     },
+    /**
+     * Report the live state of the stream.
+     *
+     * `latency` and `targetLatency` come from hls.js on the MSE path, where
+     * they are measured against `EXT-X-PROGRAM-DATE-TIME` drift when the
+     * manifest carries it. On the native path there is no latency API, so both
+     * are approximations: latency is the distance to `seekable.end`, and the
+     * target is whatever an earlier hls.js session on this source measured
+     * (an AirPlay handoff) before it falls back to 3 seconds. Parking a viewer
+     * of a 2-second-target stream 3 seconds back was the previous behaviour,
+     * and it is a full target latency of drift.
+     *
+     * @returns Live info, or null for VOD and before a pipeline exists
+     */
     getLiveInfo() {
       const live = api?.getState("live") || false;
       if (!live) return null;
+      const metrics = readLiveMetrics();
       if (isNative) {
+        const targetLatency2 = metrics?.targetLatency ?? DEFAULT_TARGET_LATENCY;
+        const seekableEnd = video?.seekable?.length ? video.seekable.end(video.seekable.length - 1) : void 0;
         return {
           isLive: true,
-          latency: 0,
-          targetLatency: 3,
+          latency: metrics?.latency ?? 0,
+          targetLatency: targetLatency2,
           drift: 0,
-          liveSyncPosition: video?.seekable?.length ? Math.max(0, video.seekable.end(video.seekable.length - 1) - 3) : void 0
+          liveSyncPosition: seekableEnd !== void 0 ? Math.max(0, seekableEnd - targetLatency2) : void 0,
+          lowLatency: metrics?.lowLatency ?? false
         };
       }
       if (!hls) return null;
+      const targetLatency = hls.targetLatency || metrics?.targetLatency || DEFAULT_TARGET_LATENCY;
       return {
         isLive: true,
         latency: hls.latency || 0,
-        targetLatency: hls.targetLatency || 3,
+        targetLatency,
         drift: hls.drift || 0,
-        liveSyncPosition: hls.liveSyncPosition ?? (video?.seekable?.length ? Math.max(0, video.seekable.end(video.seekable.length - 1) - 3) : void 0)
+        liveSyncPosition: hls.liveSyncPosition ?? (video?.seekable?.length ? Math.max(0, video.seekable.end(video.seekable.length - 1) - targetLatency) : void 0),
+        lowLatency: metrics?.lowLatency ?? false
       };
     },
     /**
@@ -1405,10 +1587,12 @@ function createHLSPluginWith(loader, variant, config) {
       const wasPlaying = api?.getState("playing") || false;
       const currentTime = video?.currentTime || 0;
       const savedSrc = currentSrc;
+      const savedTargetLatency = lastKnownTargetLatency;
       const session = ++loadSession;
       cancelReconnect();
       cleanup(new Error("HLS load cancelled: switching to native HLS"));
       currentSrc = savedSrc;
+      lastKnownTargetLatency = savedTargetLatency;
       await loadNative(savedSrc);
       if (session !== loadSession) return;
       if (video && currentTime > 0) {
@@ -1444,10 +1628,12 @@ function createHLSPluginWith(loader, variant, config) {
       const wasPlaying = api?.getState("playing") || false;
       const currentTime = video?.currentTime || 0;
       const savedSrc = currentSrc;
+      const savedTargetLatency = lastKnownTargetLatency;
       const session = ++loadSession;
       cancelReconnect();
       cleanup(new Error("HLS load cancelled: switching to hls.js"));
       currentSrc = savedSrc;
+      lastKnownTargetLatency = savedTargetLatency;
       await loadWithHlsJs(savedSrc);
       if (session !== loadSession) return;
       if (video && currentTime > 0) {
@@ -1469,5 +1655,7 @@ function createHLSPluginWith(loader, variant, config) {
 export {
   __export,
   sanitizeUrl,
+  DEFAULT_TARGET_LATENCY,
+  computeLiveMetrics,
   createHLSPluginWith
 };