@scarlett-player/captions 1.15.3 → 1.16.0

package/README.md

@@ -54,7 +54,7 @@ const player = await createPlayer({
 | `label` | `string` | required | Human readable name shown in the picker |
 | `src` | `string` | required | WebVTT URL. Cross-origin URLs need CORS |
 | `kind` | `'subtitles' \| 'captions'` | `'subtitles'` | Track kind |
-| `default` | `boolean` | - | Declared on the interface but not read. Every track starts disabled and selection is managed by the plugin; use `autoSelect` and `defaultLanguage` instead |
+| `default` | `boolean` | - | Select this source once the media loads. Beats `defaultLanguage` and applies even with `autoSelect` off, so it is how you name one specific track. A track the browser is already showing still wins, and selection happens once per media. Mark at most one source |
 
 ## How tracks reach the player
 

package/dist/index.cjs

@@ -26,7 +26,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/version.ts
-var PKG_VERSION = true ? "1.15.3" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.16.0" : "0.0.0-dev";
 
 // src/index.ts
 var HLS_SUBTITLE_TRACKS_UPDATED = "hlsSubtitleTracksUpdated";
@@ -36,6 +36,7 @@ function createCaptionsPlugin(config = {}) {
   let api = null;
   let video = null;
   let addedTrackElements = [];
+  let defaultTrackElement = null;
   let hlsSubtitleHandler = null;
   let hlsSubtitleSwitchHandler = null;
   let observedTextTracks = null;
@@ -45,6 +46,7 @@ function createCaptionsPlugin(config = {}) {
   const extractFromHLS = config.extractFromHLS !== false;
   const autoSelect = config.autoSelect ?? false;
   const defaultLanguage = config.defaultLanguage ?? "en";
+  const defaultSource = config.sources?.find((source) => source.default) ?? null;
   const getVideo = () => {
     if (video) return video;
     video = api?.container.querySelector("video") ?? null;
@@ -55,6 +57,7 @@ function createCaptionsPlugin(config = {}) {
       trackEl.parentNode?.removeChild(trackEl);
     }
     addedTrackElements = [];
+    defaultTrackElement = null;
     api?.setState("textTracks", []);
     api?.setState("currentTextTrack", null);
   };
@@ -113,17 +116,37 @@ function createCaptionsPlugin(config = {}) {
     }
     syncTracksToState();
   };
+  const markedTrack = (tracks) => {
+    if (!defaultSource) return void 0;
+    const videoEl = getVideo();
+    const textTrack = defaultTrackElement?.track;
+    if (videoEl && textTrack) {
+      for (let i = 0; i < videoEl.textTracks.length; i++) {
+        if (videoEl.textTracks[i] !== textTrack) continue;
+        const own = tracks.find((t) => t.id === `track-${i}`);
+        if (own) return own;
+      }
+    }
+    return tracks.find(
+      (t) => t.language === defaultSource.language && (!defaultSource.label || t.label === defaultSource.label)
+    );
+  };
   const maybeAutoSelect = () => {
-    if (!autoSelect || hasAutoSelected) return;
+    if (!autoSelect && !defaultSource || hasAutoSelected) return;
     if (api?.getState("currentTextTrack")) {
       hasAutoSelected = true;
       return;
     }
     const tracks = api?.getState("textTracks") || [];
-    const match = tracks.find((t) => t.language === defaultLanguage);
+    const marked = markedTrack(tracks);
+    const match = marked ?? (autoSelect ? tracks.find((t) => t.language === defaultLanguage) : void 0);
     if (!match) return;
     selectTrack(match.id);
-    api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+    api?.logger.debug("Selected caption track on load", {
+      language: match.language,
+      id: match.id,
+      reason: marked ? "source default" : "defaultLanguage"
+    });
   };
   const handleTextTracksChanged = () => {
     syncTracksToState();
@@ -203,7 +226,8 @@ function createCaptionsPlugin(config = {}) {
   const initSources = () => {
     if (!config.sources?.length) return;
     for (const source of config.sources) {
-      addTrackElement(source);
+      const trackEl = addTrackElement(source);
+      if (source === defaultSource) defaultTrackElement = trackEl;
     }
   };
   return {

package/dist/index.d.cts

@@ -12,7 +12,13 @@ interface CaptionSource {
     src: string;
     /** Track kind - default: 'subtitles' */
     kind?: 'subtitles' | 'captions';
-    /** Whether this track should be selected by default */
+    /**
+     * Select this track once the media loads.
+     *
+     * Beats `defaultLanguage`, and applies even with `autoSelect` off. A
+     * viewer's own pick still wins: selection happens once per media, and a
+     * track already showing stands. Mark at most one source.
+     */
     default?: boolean;
 }
 interface CaptionsPluginConfig {

package/dist/index.d.ts

@@ -12,7 +12,13 @@ interface CaptionSource {
     src: string;
     /** Track kind - default: 'subtitles' */
     kind?: 'subtitles' | 'captions';
-    /** Whether this track should be selected by default */
+    /**
+     * Select this track once the media loads.
+     *
+     * Beats `defaultLanguage`, and applies even with `autoSelect` off. A
+     * viewer's own pick still wins: selection happens once per media, and a
+     * track already showing stands. Mark at most one source.
+     */
     default?: boolean;
 }
 interface CaptionsPluginConfig {

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var PKG_VERSION = true ? "1.15.3" : "0.0.0-dev";
+var PKG_VERSION = true ? "1.16.0" : "0.0.0-dev";
 
 // src/index.ts
 var HLS_SUBTITLE_TRACKS_UPDATED = "hlsSubtitleTracksUpdated";
@@ -9,6 +9,7 @@ function createCaptionsPlugin(config = {}) {
   let api = null;
   let video = null;
   let addedTrackElements = [];
+  let defaultTrackElement = null;
   let hlsSubtitleHandler = null;
   let hlsSubtitleSwitchHandler = null;
   let observedTextTracks = null;
@@ -18,6 +19,7 @@ function createCaptionsPlugin(config = {}) {
   const extractFromHLS = config.extractFromHLS !== false;
   const autoSelect = config.autoSelect ?? false;
   const defaultLanguage = config.defaultLanguage ?? "en";
+  const defaultSource = config.sources?.find((source) => source.default) ?? null;
   const getVideo = () => {
     if (video) return video;
     video = api?.container.querySelector("video") ?? null;
@@ -28,6 +30,7 @@ function createCaptionsPlugin(config = {}) {
       trackEl.parentNode?.removeChild(trackEl);
     }
     addedTrackElements = [];
+    defaultTrackElement = null;
     api?.setState("textTracks", []);
     api?.setState("currentTextTrack", null);
   };
@@ -86,17 +89,37 @@ function createCaptionsPlugin(config = {}) {
     }
     syncTracksToState();
   };
+  const markedTrack = (tracks) => {
+    if (!defaultSource) return void 0;
+    const videoEl = getVideo();
+    const textTrack = defaultTrackElement?.track;
+    if (videoEl && textTrack) {
+      for (let i = 0; i < videoEl.textTracks.length; i++) {
+        if (videoEl.textTracks[i] !== textTrack) continue;
+        const own = tracks.find((t) => t.id === `track-${i}`);
+        if (own) return own;
+      }
+    }
+    return tracks.find(
+      (t) => t.language === defaultSource.language && (!defaultSource.label || t.label === defaultSource.label)
+    );
+  };
   const maybeAutoSelect = () => {
-    if (!autoSelect || hasAutoSelected) return;
+    if (!autoSelect && !defaultSource || hasAutoSelected) return;
     if (api?.getState("currentTextTrack")) {
       hasAutoSelected = true;
       return;
     }
     const tracks = api?.getState("textTracks") || [];
-    const match = tracks.find((t) => t.language === defaultLanguage);
+    const marked = markedTrack(tracks);
+    const match = marked ?? (autoSelect ? tracks.find((t) => t.language === defaultLanguage) : void 0);
     if (!match) return;
     selectTrack(match.id);
-    api?.logger.debug("Auto-selected caption track", { language: defaultLanguage, id: match.id });
+    api?.logger.debug("Selected caption track on load", {
+      language: match.language,
+      id: match.id,
+      reason: marked ? "source default" : "defaultLanguage"
+    });
   };
   const handleTextTracksChanged = () => {
     syncTracksToState();
@@ -176,7 +199,8 @@ function createCaptionsPlugin(config = {}) {
   const initSources = () => {
     if (!config.sources?.length) return;
     for (const source of config.sources) {
-      addTrackElement(source);
+      const trackEl = addTrackElement(source);
+      if (source === defaultSource) defaultTrackElement = trackEl;
     }
   };
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scarlett-player/captions",
-  "version": "1.15.3",
+  "version": "1.16.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.15.3"
+    "@scarlett-player/core": "1.16.0"
   },
   "keywords": [
     "video",