@scarlett-player/hls 1.11.0 → 1.12.0

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_TARGET_LATENCY: () => DEFAULT_TARGET_LATENCY,
+  computeLiveMetrics: () => computeLiveMetrics,
   createHLSPlugin: () => createHLSPlugin,
   default: () => index_default,
   sanitizeUrl: () => import_core.sanitizeUrl
@@ -167,6 +169,107 @@ function getInitialBandwidthEstimate(overrideBps) {
 // src/sanitize-url.ts
 var import_core = require("@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/event-map.ts
 var HLS_ERROR_TYPES = {
   NETWORK_ERROR: "networkError",
@@ -304,16 +407,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?.();
     }
@@ -353,7 +458,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);
@@ -390,15 +495,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", () => {
@@ -546,7 +647,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 = {
@@ -574,6 +675,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",
@@ -589,6 +691,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;
@@ -611,6 +716,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") || "";
@@ -660,6 +783,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();
@@ -671,27 +798,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;
@@ -888,7 +1046,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;
@@ -981,7 +1139,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) {
@@ -1023,6 +1181,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);
@@ -1460,25 +1624,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
       };
     },
     /**
@@ -1503,10 +1687,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) {
@@ -1542,10 +1728,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) {
@@ -1580,6 +1768,8 @@ function createHLSPlugin(config) {
 var index_default = createHLSPlugin;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_TARGET_LATENCY,
+  computeLiveMetrics,
   createHLSPlugin,
   sanitizeUrl
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-DnvcTuSn.cjs';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-DnvcTuSn.cjs';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './live-metrics-CoYkWhl5.cjs';
+export { D as DEFAULT_TARGET_LATENCY, b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, f as HlsLevelDetails, L as LiveMetrics, e as LiveMetricsSource, d as computeLiveMetrics } from './live-metrics-CoYkWhl5.cjs';
 export { sanitizeUrl } from '@scarlett-player/core';
 
 /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HLSPluginConfig, I as IHLSPlugin } from './types-DnvcTuSn.js';
-export { b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel } from './types-DnvcTuSn.js';
+import { H as HLSPluginConfig, I as IHLSPlugin } from './live-metrics-CoYkWhl5.js';
+export { D as DEFAULT_TARGET_LATENCY, b as HLSError, c as HLSLiveInfo, a as HLSQualityLevel, f as HlsLevelDetails, L as LiveMetrics, e as LiveMetricsSource, d as computeLiveMetrics } from './live-metrics-CoYkWhl5.js';
 export { sanitizeUrl } from '@scarlett-player/core';
 
 /**

package/dist/index.js

@@ -1,8 +1,10 @@
 import {
+  DEFAULT_TARGET_LATENCY,
   __export,
+  computeLiveMetrics,
   createHLSPluginWith,
   sanitizeUrl
-} from "./chunk-NVPSLRJY.js";
+} from "./chunk-47MU7IVX.js";
 
 // src/hls-loader.ts
 var hls_loader_exports = {};
@@ -85,6 +87,8 @@ function createHLSPlugin(config) {
 }
 var index_default = createHLSPlugin;
 export {
+  DEFAULT_TARGET_LATENCY,
+  computeLiveMetrics,
   createHLSPlugin,
   index_default as default,
   sanitizeUrl