@scarlett-player/captions 1.2.0 → 1.4.0

package/dist/index.cjs

@@ -24,11 +24,18 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
+var HLS_SUBTITLE_TRACKS_UPDATED = "hlsSubtitleTracksUpdated";
+var HLS_INSTANCE_RETRY_MS = 500;
 function createCaptionsPlugin(config = {}) {
   let api = null;
   let video = null;
   let addedTrackElements = [];
+  let hlsTrackElements = [];
   let hlsSubtitleHandler = null;
+  let observedTextTracks = null;
+  let hlsRetryTimer = null;
+  let hlsRetryUsed = false;
+  let hasAutoSelected = false;
   const extractFromHLS = config.extractFromHLS !== false;
   const autoSelect = config.autoSelect ?? false;
   const defaultLanguage = config.defaultLanguage ?? "en";
@@ -42,10 +49,18 @@ function createCaptionsPlugin(config = {}) {
       trackEl.parentNode?.removeChild(trackEl);
     }
     addedTrackElements = [];
+    hlsTrackElements = [];
     api?.setState("textTracks", []);
     api?.setState("currentTextTrack", null);
   };
-  const addTrackElement = (source) => {
+  const removeHlsTrackElements = () => {
+    for (const trackEl of hlsTrackElements) {
+      trackEl.parentNode?.removeChild(trackEl);
+      addedTrackElements = addedTrackElements.filter((el) => el !== trackEl);
+    }
+    hlsTrackElements = [];
+  };
+  const addTrackElement = (source, origin = "config") => {
     const videoEl = getVideo();
     if (!videoEl) throw new Error("No video element");
     const trackEl = document.createElement("track");
@@ -56,6 +71,9 @@ function createCaptionsPlugin(config = {}) {
     trackEl.default = false;
     videoEl.appendChild(trackEl);
     addedTrackElements.push(trackEl);
+    if (origin === "hls") {
+      hlsTrackElements.push(trackEl);
+    }
     if (trackEl.track) {
       trackEl.track.mode = "disabled";
     }
@@ -87,6 +105,7 @@ function createCaptionsPlugin(config = {}) {
   const selectTrack = (trackId) => {
     const videoEl = getVideo();
     if (!videoEl) return;
+    hasAutoSelected = true;
     for (let i = 0; i < videoEl.textTracks.length; i++) {
       const track = videoEl.textTracks[i];
       if (track.kind !== "subtitles" && track.kind !== "captions") continue;
@@ -99,6 +118,43 @@ function createCaptionsPlugin(config = {}) {
     }
     syncTracksToState();
   };
+  const maybeAutoSelect = () => {
+    if (!autoSelect || hasAutoSelected) return;
+    if (api?.getState("currentTextTrack")) {
+      hasAutoSelected = true;
+      return;
+    }
+    const tracks = api?.getState("textTracks") || [];
+    const match = tracks.find((t) => t.language === defaultLanguage);
+    if (!match) return;
+    selectTrack(match.id);
+    api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+  };
+  const handleTextTracksChanged = () => {
+    syncTracksToState();
+    maybeAutoSelect();
+  };
+  const observeTextTracks = () => {
+    const videoEl = getVideo();
+    if (!videoEl || observedTextTracks === videoEl.textTracks) return;
+    unobserveTextTracks();
+    const list = videoEl.textTracks;
+    if (typeof list?.addEventListener !== "function") return;
+    observedTextTracks = list;
+    observedTextTracks.addEventListener("addtrack", handleTextTracksChanged);
+    observedTextTracks.addEventListener("removetrack", handleTextTracksChanged);
+    observedTextTracks.addEventListener("change", handleTextTracksChanged);
+  };
+  const unobserveTextTracks = () => {
+    if (typeof observedTextTracks?.removeEventListener !== "function") {
+      observedTextTracks = null;
+      return;
+    }
+    observedTextTracks.removeEventListener("addtrack", handleTextTracksChanged);
+    observedTextTracks.removeEventListener("removetrack", handleTextTracksChanged);
+    observedTextTracks.removeEventListener("change", handleTextTracksChanged);
+    observedTextTracks = null;
+  };
   const extractHlsSubtitles = () => {
     if (!extractFromHLS || !api) return;
     const hlsPlugin = api.getPlugin("hls-provider");
@@ -108,35 +164,55 @@ function createCaptionsPlugin(config = {}) {
     api.logger.debug("Extracting HLS subtitle tracks", {
       count: hlsInstance.subtitleTracks.length
     });
+    removeHlsTrackElements();
     for (const hlsTrack of hlsInstance.subtitleTracks) {
-      addTrackElement({
-        language: hlsTrack.lang || "unknown",
-        label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
-        src: hlsTrack.url,
-        kind: "subtitles"
-      });
+      addTrackElement(
+        {
+          language: hlsTrack.lang || "unknown",
+          label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
+          src: hlsTrack.url,
+          kind: "subtitles"
+        },
+        "hls"
+      );
     }
     syncTracksToState();
-    if (autoSelect) {
-      autoSelectTrack();
+    maybeAutoSelect();
+  };
+  const unsubscribeFromHls = () => {
+    if (hlsRetryTimer) {
+      clearTimeout(hlsRetryTimer);
+      hlsRetryTimer = null;
     }
+    if (!hlsSubtitleHandler) return;
+    const hlsInstance = api?.getPlugin("hls-provider")?.getHlsInstance();
+    hlsInstance?.off(HLS_SUBTITLE_TRACKS_UPDATED, hlsSubtitleHandler);
+    hlsSubtitleHandler = null;
   };
-  const autoSelectTrack = () => {
-    const tracks = api?.getState("textTracks") || [];
-    const match = tracks.find((t) => t.language === defaultLanguage);
-    if (match) {
-      selectTrack(match.id);
-      api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+  const syncFromHls = () => {
+    if (!extractFromHLS || !api) return;
+    const hlsPlugin = api.getPlugin("hls-provider");
+    if (!hlsPlugin || hlsPlugin.isNativeHLS()) return;
+    const hlsInstance = hlsPlugin.getHlsInstance();
+    if (!hlsInstance) {
+      if (!hlsRetryUsed) {
+        hlsRetryUsed = true;
+        hlsRetryTimer = setTimeout(() => {
+          hlsRetryTimer = null;
+          syncFromHls();
+        }, HLS_INSTANCE_RETRY_MS);
+      }
+      return;
     }
+    unsubscribeFromHls();
+    hlsSubtitleHandler = () => extractHlsSubtitles();
+    hlsInstance.on(HLS_SUBTITLE_TRACKS_UPDATED, hlsSubtitleHandler);
+    extractHlsSubtitles();
   };
   const initSources = () => {
     if (!config.sources?.length) return;
     for (const source of config.sources) {
-      addTrackElement(source);
-    }
-    syncTracksToState();
-    if (autoSelect) {
-      autoSelectTrack();
+      addTrackElement(source, "config");
     }
   };
   return {
@@ -155,33 +231,36 @@ function createCaptionsPlugin(config = {}) {
       });
       const unsubLoaded = api.on("media:loaded", () => {
         video = null;
+        hasAutoSelected = false;
+        hlsRetryUsed = false;
         cleanupTracks();
         initSources();
-        if (extractFromHLS) {
-          setTimeout(extractHlsSubtitles, 500);
-        }
+        observeTextTracks();
+        syncTracksToState();
+        maybeAutoSelect();
+        syncFromHls();
       });
       const unsubLoadRequest = api.on("media:load-request", () => {
         video = null;
+        hasAutoSelected = false;
+        hlsRetryUsed = false;
+        unsubscribeFromHls();
+        unobserveTextTracks();
         cleanupTracks();
       });
       api.onDestroy(() => {
         unsubTrackText();
         unsubLoaded();
         unsubLoadRequest();
+        unsubscribeFromHls();
+        unobserveTextTracks();
         cleanupTracks();
-        if (hlsSubtitleHandler) {
-          const hlsPlugin = api?.getPlugin("hls-provider");
-          const hlsInstance = hlsPlugin?.getHlsInstance();
-          if (hlsInstance) {
-            hlsInstance.off("SUBTITLE_TRACKS_UPDATED", hlsSubtitleHandler);
-          }
-          hlsSubtitleHandler = null;
-        }
       });
     },
     destroy() {
       api?.logger.debug("Captions plugin destroyed");
+      unsubscribeFromHls();
+      unobserveTextTracks();
       cleanupTracks();
       video = null;
       api = null;

package/dist/index.d.cts

@@ -33,7 +33,9 @@ interface CaptionsPluginConfig {
  *
  * Provides WebVTT subtitle/caption support with:
  * - External WebVTT file loading via <track> elements
- * - HLS.js subtitle track extraction
+ * - HLS.js subtitle track extraction, driven by Hls.Events.SUBTITLE_TRACKS_UPDATED
+ *   (emitted as 'hlsSubtitleTracksUpdated')
+ * - Native HLS support (Safari/iOS) by observing the video's TextTrackList
  * - Browser-native rendering (no custom VTT parser)
  * - State sync with core textTracks/currentTextTrack
  * - Automatic cleanup on source change

package/dist/index.d.ts

@@ -33,7 +33,9 @@ interface CaptionsPluginConfig {
  *
  * Provides WebVTT subtitle/caption support with:
  * - External WebVTT file loading via <track> elements
- * - HLS.js subtitle track extraction
+ * - HLS.js subtitle track extraction, driven by Hls.Events.SUBTITLE_TRACKS_UPDATED
+ *   (emitted as 'hlsSubtitleTracksUpdated')
+ * - Native HLS support (Safari/iOS) by observing the video's TextTrackList
  * - Browser-native rendering (no custom VTT parser)
  * - State sync with core textTracks/currentTextTrack
  * - Automatic cleanup on source change

package/dist/index.js

@@ -1,9 +1,16 @@
 // src/index.ts
+var HLS_SUBTITLE_TRACKS_UPDATED = "hlsSubtitleTracksUpdated";
+var HLS_INSTANCE_RETRY_MS = 500;
 function createCaptionsPlugin(config = {}) {
   let api = null;
   let video = null;
   let addedTrackElements = [];
+  let hlsTrackElements = [];
   let hlsSubtitleHandler = null;
+  let observedTextTracks = null;
+  let hlsRetryTimer = null;
+  let hlsRetryUsed = false;
+  let hasAutoSelected = false;
   const extractFromHLS = config.extractFromHLS !== false;
   const autoSelect = config.autoSelect ?? false;
   const defaultLanguage = config.defaultLanguage ?? "en";
@@ -17,10 +24,18 @@ function createCaptionsPlugin(config = {}) {
       trackEl.parentNode?.removeChild(trackEl);
     }
     addedTrackElements = [];
+    hlsTrackElements = [];
     api?.setState("textTracks", []);
     api?.setState("currentTextTrack", null);
   };
-  const addTrackElement = (source) => {
+  const removeHlsTrackElements = () => {
+    for (const trackEl of hlsTrackElements) {
+      trackEl.parentNode?.removeChild(trackEl);
+      addedTrackElements = addedTrackElements.filter((el) => el !== trackEl);
+    }
+    hlsTrackElements = [];
+  };
+  const addTrackElement = (source, origin = "config") => {
     const videoEl = getVideo();
     if (!videoEl) throw new Error("No video element");
     const trackEl = document.createElement("track");
@@ -31,6 +46,9 @@ function createCaptionsPlugin(config = {}) {
     trackEl.default = false;
     videoEl.appendChild(trackEl);
     addedTrackElements.push(trackEl);
+    if (origin === "hls") {
+      hlsTrackElements.push(trackEl);
+    }
     if (trackEl.track) {
       trackEl.track.mode = "disabled";
     }
@@ -62,6 +80,7 @@ function createCaptionsPlugin(config = {}) {
   const selectTrack = (trackId) => {
     const videoEl = getVideo();
     if (!videoEl) return;
+    hasAutoSelected = true;
     for (let i = 0; i < videoEl.textTracks.length; i++) {
       const track = videoEl.textTracks[i];
       if (track.kind !== "subtitles" && track.kind !== "captions") continue;
@@ -74,6 +93,43 @@ function createCaptionsPlugin(config = {}) {
     }
     syncTracksToState();
   };
+  const maybeAutoSelect = () => {
+    if (!autoSelect || hasAutoSelected) return;
+    if (api?.getState("currentTextTrack")) {
+      hasAutoSelected = true;
+      return;
+    }
+    const tracks = api?.getState("textTracks") || [];
+    const match = tracks.find((t) => t.language === defaultLanguage);
+    if (!match) return;
+    selectTrack(match.id);
+    api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+  };
+  const handleTextTracksChanged = () => {
+    syncTracksToState();
+    maybeAutoSelect();
+  };
+  const observeTextTracks = () => {
+    const videoEl = getVideo();
+    if (!videoEl || observedTextTracks === videoEl.textTracks) return;
+    unobserveTextTracks();
+    const list = videoEl.textTracks;
+    if (typeof list?.addEventListener !== "function") return;
+    observedTextTracks = list;
+    observedTextTracks.addEventListener("addtrack", handleTextTracksChanged);
+    observedTextTracks.addEventListener("removetrack", handleTextTracksChanged);
+    observedTextTracks.addEventListener("change", handleTextTracksChanged);
+  };
+  const unobserveTextTracks = () => {
+    if (typeof observedTextTracks?.removeEventListener !== "function") {
+      observedTextTracks = null;
+      return;
+    }
+    observedTextTracks.removeEventListener("addtrack", handleTextTracksChanged);
+    observedTextTracks.removeEventListener("removetrack", handleTextTracksChanged);
+    observedTextTracks.removeEventListener("change", handleTextTracksChanged);
+    observedTextTracks = null;
+  };
   const extractHlsSubtitles = () => {
     if (!extractFromHLS || !api) return;
     const hlsPlugin = api.getPlugin("hls-provider");
@@ -83,35 +139,55 @@ function createCaptionsPlugin(config = {}) {
     api.logger.debug("Extracting HLS subtitle tracks", {
       count: hlsInstance.subtitleTracks.length
     });
+    removeHlsTrackElements();
     for (const hlsTrack of hlsInstance.subtitleTracks) {
-      addTrackElement({
-        language: hlsTrack.lang || "unknown",
-        label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
-        src: hlsTrack.url,
-        kind: "subtitles"
-      });
+      addTrackElement(
+        {
+          language: hlsTrack.lang || "unknown",
+          label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
+          src: hlsTrack.url,
+          kind: "subtitles"
+        },
+        "hls"
+      );
     }
     syncTracksToState();
-    if (autoSelect) {
-      autoSelectTrack();
+    maybeAutoSelect();
+  };
+  const unsubscribeFromHls = () => {
+    if (hlsRetryTimer) {
+      clearTimeout(hlsRetryTimer);
+      hlsRetryTimer = null;
     }
+    if (!hlsSubtitleHandler) return;
+    const hlsInstance = api?.getPlugin("hls-provider")?.getHlsInstance();
+    hlsInstance?.off(HLS_SUBTITLE_TRACKS_UPDATED, hlsSubtitleHandler);
+    hlsSubtitleHandler = null;
   };
-  const autoSelectTrack = () => {
-    const tracks = api?.getState("textTracks") || [];
-    const match = tracks.find((t) => t.language === defaultLanguage);
-    if (match) {
-      selectTrack(match.id);
-      api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+  const syncFromHls = () => {
+    if (!extractFromHLS || !api) return;
+    const hlsPlugin = api.getPlugin("hls-provider");
+    if (!hlsPlugin || hlsPlugin.isNativeHLS()) return;
+    const hlsInstance = hlsPlugin.getHlsInstance();
+    if (!hlsInstance) {
+      if (!hlsRetryUsed) {
+        hlsRetryUsed = true;
+        hlsRetryTimer = setTimeout(() => {
+          hlsRetryTimer = null;
+          syncFromHls();
+        }, HLS_INSTANCE_RETRY_MS);
+      }
+      return;
     }
+    unsubscribeFromHls();
+    hlsSubtitleHandler = () => extractHlsSubtitles();
+    hlsInstance.on(HLS_SUBTITLE_TRACKS_UPDATED, hlsSubtitleHandler);
+    extractHlsSubtitles();
   };
   const initSources = () => {
     if (!config.sources?.length) return;
     for (const source of config.sources) {
-      addTrackElement(source);
-    }
-    syncTracksToState();
-    if (autoSelect) {
-      autoSelectTrack();
+      addTrackElement(source, "config");
     }
   };
   return {
@@ -130,33 +206,36 @@ function createCaptionsPlugin(config = {}) {
       });
       const unsubLoaded = api.on("media:loaded", () => {
         video = null;
+        hasAutoSelected = false;
+        hlsRetryUsed = false;
         cleanupTracks();
         initSources();
-        if (extractFromHLS) {
-          setTimeout(extractHlsSubtitles, 500);
-        }
+        observeTextTracks();
+        syncTracksToState();
+        maybeAutoSelect();
+        syncFromHls();
       });
       const unsubLoadRequest = api.on("media:load-request", () => {
         video = null;
+        hasAutoSelected = false;
+        hlsRetryUsed = false;
+        unsubscribeFromHls();
+        unobserveTextTracks();
         cleanupTracks();
       });
       api.onDestroy(() => {
         unsubTrackText();
         unsubLoaded();
         unsubLoadRequest();
+        unsubscribeFromHls();
+        unobserveTextTracks();
         cleanupTracks();
-        if (hlsSubtitleHandler) {
-          const hlsPlugin = api?.getPlugin("hls-provider");
-          const hlsInstance = hlsPlugin?.getHlsInstance();
-          if (hlsInstance) {
-            hlsInstance.off("SUBTITLE_TRACKS_UPDATED", hlsSubtitleHandler);
-          }
-          hlsSubtitleHandler = null;
-        }
       });
     },
     destroy() {
       api?.logger.debug("Captions plugin destroyed");
+      unsubscribeFromHls();
+      unobserveTextTracks();
       cleanupTracks();
       video = null;
       api = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/captions",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Captions Plugin for Scarlett Player - WebVTT subtitles and closed captions",
   "type": "module",
   "main": "dist/index.cjs",
@@ -30,7 +30,7 @@
     "tsup": "^8.5.1",
     "typescript": "^5.3.0",
     "vitest": "^1.6.0",
-    "@scarlett-player/core": "1.2.0"
+    "@scarlett-player/core": "1.4.0"
   },
   "keywords": [
     "video",