@scarlett-player/captions 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hackney Enterprises Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,195 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createCaptionsPlugin: () => createCaptionsPlugin,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+function createCaptionsPlugin(config = {}) {
+  let api = null;
+  let video = null;
+  let addedTrackElements = [];
+  let hlsSubtitleHandler = null;
+  const extractFromHLS = config.extractFromHLS !== false;
+  const autoSelect = config.autoSelect ?? false;
+  const defaultLanguage = config.defaultLanguage ?? "en";
+  const getVideo = () => {
+    if (video) return video;
+    video = api?.container.querySelector("video") ?? null;
+    return video;
+  };
+  const cleanupTracks = () => {
+    for (const trackEl of addedTrackElements) {
+      trackEl.parentNode?.removeChild(trackEl);
+    }
+    addedTrackElements = [];
+    api?.setState("textTracks", []);
+    api?.setState("currentTextTrack", null);
+  };
+  const addTrackElement = (source) => {
+    const videoEl = getVideo();
+    if (!videoEl) throw new Error("No video element");
+    const trackEl = document.createElement("track");
+    trackEl.kind = source.kind || "subtitles";
+    trackEl.label = source.label;
+    trackEl.srclang = source.language;
+    trackEl.src = source.src;
+    trackEl.default = false;
+    videoEl.appendChild(trackEl);
+    addedTrackElements.push(trackEl);
+    if (trackEl.track) {
+      trackEl.track.mode = "disabled";
+    }
+    return trackEl;
+  };
+  const syncTracksToState = () => {
+    const videoEl = getVideo();
+    if (!videoEl) return;
+    const tracks = [];
+    let currentTrack = null;
+    for (let i = 0; i < videoEl.textTracks.length; i++) {
+      const track = videoEl.textTracks[i];
+      if (track.kind !== "subtitles" && track.kind !== "captions") continue;
+      const scarlettTrack = {
+        id: `track-${i}`,
+        label: track.label || `Track ${i + 1}`,
+        language: track.language || "",
+        kind: track.kind,
+        active: track.mode === "showing"
+      };
+      tracks.push(scarlettTrack);
+      if (track.mode === "showing") {
+        currentTrack = scarlettTrack;
+      }
+    }
+    api?.setState("textTracks", tracks);
+    api?.setState("currentTextTrack", currentTrack);
+  };
+  const selectTrack = (trackId) => {
+    const videoEl = getVideo();
+    if (!videoEl) return;
+    for (let i = 0; i < videoEl.textTracks.length; i++) {
+      const track = videoEl.textTracks[i];
+      if (track.kind !== "subtitles" && track.kind !== "captions") continue;
+      const id = `track-${i}`;
+      if (trackId && id === trackId) {
+        track.mode = "showing";
+      } else {
+        track.mode = "disabled";
+      }
+    }
+    syncTracksToState();
+  };
+  const extractHlsSubtitles = () => {
+    if (!extractFromHLS || !api) return;
+    const hlsPlugin = api.getPlugin("hls-provider");
+    if (!hlsPlugin || hlsPlugin.isNativeHLS()) return;
+    const hlsInstance = hlsPlugin.getHlsInstance();
+    if (!hlsInstance?.subtitleTracks?.length) return;
+    api.logger.debug("Extracting HLS subtitle tracks", {
+      count: hlsInstance.subtitleTracks.length
+    });
+    for (const hlsTrack of hlsInstance.subtitleTracks) {
+      addTrackElement({
+        language: hlsTrack.lang || "unknown",
+        label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
+        src: hlsTrack.url,
+        kind: "subtitles"
+      });
+    }
+    syncTracksToState();
+    if (autoSelect) {
+      autoSelectTrack();
+    }
+  };
+  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 initSources = () => {
+    if (!config.sources?.length) return;
+    for (const source of config.sources) {
+      addTrackElement(source);
+    }
+    syncTracksToState();
+    if (autoSelect) {
+      autoSelectTrack();
+    }
+  };
+  return {
+    id: "captions",
+    name: "Captions",
+    version: "1.0.0",
+    type: "feature",
+    description: "WebVTT subtitles and closed captions with HLS extraction",
+    init(pluginApi) {
+      api = pluginApi;
+      api.logger.debug("Captions plugin initialized");
+      api.setState("textTracks", []);
+      api.setState("currentTextTrack", null);
+      const unsubTrackText = api.on("track:text", ({ trackId }) => {
+        selectTrack(trackId);
+      });
+      const unsubLoaded = api.on("media:loaded", () => {
+        video = null;
+        cleanupTracks();
+        initSources();
+        if (extractFromHLS) {
+          setTimeout(extractHlsSubtitles, 500);
+        }
+      });
+      const unsubLoadRequest = api.on("media:load-request", () => {
+        video = null;
+        cleanupTracks();
+      });
+      api.onDestroy(() => {
+        unsubTrackText();
+        unsubLoaded();
+        unsubLoadRequest();
+        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");
+      cleanupTracks();
+      video = null;
+      api = null;
+    }
+  };
+}
+var index_default = createCaptionsPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createCaptionsPlugin
+});

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Captions Plugin Types
+ */
+interface CaptionSource {
+    /** BCP 47 language code (e.g., 'en', 'es') */
+    language: string;
+    /** Human-readable label (e.g., 'English', 'Spanish') */
+    label: string;
+    /** WebVTT file URL */
+    src: string;
+    /** Track kind — default: 'subtitles' */
+    kind?: 'subtitles' | 'captions';
+    /** Whether this track should be selected by default */
+    default?: boolean;
+}
+interface CaptionsPluginConfig {
+    /** External caption sources (WebVTT URLs) */
+    sources?: CaptionSource[];
+    /** Auto-extract subtitle tracks from HLS manifests — default: true */
+    extractFromHLS?: boolean;
+    /** Auto-select a track on load — default: false */
+    autoSelect?: boolean;
+    /** Preferred language for auto-select (BCP 47 code) — default: 'en' */
+    defaultLanguage?: string;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+
+/**
+ * Captions Plugin for Scarlett Player
+ *
+ * Provides WebVTT subtitle/caption support with:
+ * - External WebVTT file loading via <track> elements
+ * - HLS.js subtitle track extraction
+ * - Browser-native rendering (no custom VTT parser)
+ * - State sync with core textTracks/currentTextTrack
+ * - Automatic cleanup on source change
+ *
+ * Works with existing UI controls:
+ * - CaptionsButton (toggle on/off)
+ * - SettingsMenu captions submenu
+ */
+
+/**
+ * Create a Captions Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Captions Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createCaptionsPlugin } from '@scarlett-player/captions';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: '#player',
+ *   plugins: [
+ *     createCaptionsPlugin({
+ *       sources: [
+ *         { language: 'en', label: 'English', src: '/subs/en.vtt' },
+ *         { language: 'es', label: 'Spanish', src: '/subs/es.vtt' },
+ *       ],
+ *       autoSelect: true,
+ *       defaultLanguage: 'en',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createCaptionsPlugin(config?: CaptionsPluginConfig): Plugin;
+
+export { type CaptionSource, type CaptionsPluginConfig, createCaptionsPlugin, createCaptionsPlugin as default };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { Plugin } from '@scarlett-player/core';
+
+/**
+ * Captions Plugin Types
+ */
+interface CaptionSource {
+    /** BCP 47 language code (e.g., 'en', 'es') */
+    language: string;
+    /** Human-readable label (e.g., 'English', 'Spanish') */
+    label: string;
+    /** WebVTT file URL */
+    src: string;
+    /** Track kind — default: 'subtitles' */
+    kind?: 'subtitles' | 'captions';
+    /** Whether this track should be selected by default */
+    default?: boolean;
+}
+interface CaptionsPluginConfig {
+    /** External caption sources (WebVTT URLs) */
+    sources?: CaptionSource[];
+    /** Auto-extract subtitle tracks from HLS manifests — default: true */
+    extractFromHLS?: boolean;
+    /** Auto-select a track on load — default: false */
+    autoSelect?: boolean;
+    /** Preferred language for auto-select (BCP 47 code) — default: 'en' */
+    defaultLanguage?: string;
+    /** Index signature for PluginConfig compatibility */
+    [key: string]: unknown;
+}
+
+/**
+ * Captions Plugin for Scarlett Player
+ *
+ * Provides WebVTT subtitle/caption support with:
+ * - External WebVTT file loading via <track> elements
+ * - HLS.js subtitle track extraction
+ * - Browser-native rendering (no custom VTT parser)
+ * - State sync with core textTracks/currentTextTrack
+ * - Automatic cleanup on source change
+ *
+ * Works with existing UI controls:
+ * - CaptionsButton (toggle on/off)
+ * - SettingsMenu captions submenu
+ */
+
+/**
+ * Create a Captions Plugin instance.
+ *
+ * @param config - Plugin configuration
+ * @returns Captions Plugin instance
+ *
+ * @example
+ * ```ts
+ * import { createCaptionsPlugin } from '@scarlett-player/captions';
+ *
+ * const player = new ScarlettPlayer({
+ *   container: '#player',
+ *   plugins: [
+ *     createCaptionsPlugin({
+ *       sources: [
+ *         { language: 'en', label: 'English', src: '/subs/en.vtt' },
+ *         { language: 'es', label: 'Spanish', src: '/subs/es.vtt' },
+ *       ],
+ *       autoSelect: true,
+ *       defaultLanguage: 'en',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function createCaptionsPlugin(config?: CaptionsPluginConfig): Plugin;
+
+export { type CaptionSource, type CaptionsPluginConfig, createCaptionsPlugin, createCaptionsPlugin as default };

package/dist/index.js

@@ -0,0 +1,170 @@
+// src/index.ts
+function createCaptionsPlugin(config = {}) {
+  let api = null;
+  let video = null;
+  let addedTrackElements = [];
+  let hlsSubtitleHandler = null;
+  const extractFromHLS = config.extractFromHLS !== false;
+  const autoSelect = config.autoSelect ?? false;
+  const defaultLanguage = config.defaultLanguage ?? "en";
+  const getVideo = () => {
+    if (video) return video;
+    video = api?.container.querySelector("video") ?? null;
+    return video;
+  };
+  const cleanupTracks = () => {
+    for (const trackEl of addedTrackElements) {
+      trackEl.parentNode?.removeChild(trackEl);
+    }
+    addedTrackElements = [];
+    api?.setState("textTracks", []);
+    api?.setState("currentTextTrack", null);
+  };
+  const addTrackElement = (source) => {
+    const videoEl = getVideo();
+    if (!videoEl) throw new Error("No video element");
+    const trackEl = document.createElement("track");
+    trackEl.kind = source.kind || "subtitles";
+    trackEl.label = source.label;
+    trackEl.srclang = source.language;
+    trackEl.src = source.src;
+    trackEl.default = false;
+    videoEl.appendChild(trackEl);
+    addedTrackElements.push(trackEl);
+    if (trackEl.track) {
+      trackEl.track.mode = "disabled";
+    }
+    return trackEl;
+  };
+  const syncTracksToState = () => {
+    const videoEl = getVideo();
+    if (!videoEl) return;
+    const tracks = [];
+    let currentTrack = null;
+    for (let i = 0; i < videoEl.textTracks.length; i++) {
+      const track = videoEl.textTracks[i];
+      if (track.kind !== "subtitles" && track.kind !== "captions") continue;
+      const scarlettTrack = {
+        id: `track-${i}`,
+        label: track.label || `Track ${i + 1}`,
+        language: track.language || "",
+        kind: track.kind,
+        active: track.mode === "showing"
+      };
+      tracks.push(scarlettTrack);
+      if (track.mode === "showing") {
+        currentTrack = scarlettTrack;
+      }
+    }
+    api?.setState("textTracks", tracks);
+    api?.setState("currentTextTrack", currentTrack);
+  };
+  const selectTrack = (trackId) => {
+    const videoEl = getVideo();
+    if (!videoEl) return;
+    for (let i = 0; i < videoEl.textTracks.length; i++) {
+      const track = videoEl.textTracks[i];
+      if (track.kind !== "subtitles" && track.kind !== "captions") continue;
+      const id = `track-${i}`;
+      if (trackId && id === trackId) {
+        track.mode = "showing";
+      } else {
+        track.mode = "disabled";
+      }
+    }
+    syncTracksToState();
+  };
+  const extractHlsSubtitles = () => {
+    if (!extractFromHLS || !api) return;
+    const hlsPlugin = api.getPlugin("hls-provider");
+    if (!hlsPlugin || hlsPlugin.isNativeHLS()) return;
+    const hlsInstance = hlsPlugin.getHlsInstance();
+    if (!hlsInstance?.subtitleTracks?.length) return;
+    api.logger.debug("Extracting HLS subtitle tracks", {
+      count: hlsInstance.subtitleTracks.length
+    });
+    for (const hlsTrack of hlsInstance.subtitleTracks) {
+      addTrackElement({
+        language: hlsTrack.lang || "unknown",
+        label: hlsTrack.name || `Subtitle ${hlsTrack.id}`,
+        src: hlsTrack.url,
+        kind: "subtitles"
+      });
+    }
+    syncTracksToState();
+    if (autoSelect) {
+      autoSelectTrack();
+    }
+  };
+  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 initSources = () => {
+    if (!config.sources?.length) return;
+    for (const source of config.sources) {
+      addTrackElement(source);
+    }
+    syncTracksToState();
+    if (autoSelect) {
+      autoSelectTrack();
+    }
+  };
+  return {
+    id: "captions",
+    name: "Captions",
+    version: "1.0.0",
+    type: "feature",
+    description: "WebVTT subtitles and closed captions with HLS extraction",
+    init(pluginApi) {
+      api = pluginApi;
+      api.logger.debug("Captions plugin initialized");
+      api.setState("textTracks", []);
+      api.setState("currentTextTrack", null);
+      const unsubTrackText = api.on("track:text", ({ trackId }) => {
+        selectTrack(trackId);
+      });
+      const unsubLoaded = api.on("media:loaded", () => {
+        video = null;
+        cleanupTracks();
+        initSources();
+        if (extractFromHLS) {
+          setTimeout(extractHlsSubtitles, 500);
+        }
+      });
+      const unsubLoadRequest = api.on("media:load-request", () => {
+        video = null;
+        cleanupTracks();
+      });
+      api.onDestroy(() => {
+        unsubTrackText();
+        unsubLoaded();
+        unsubLoadRequest();
+        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");
+      cleanupTracks();
+      video = null;
+      api = null;
+    }
+  };
+}
+var index_default = createCaptionsPlugin;
+export {
+  createCaptionsPlugin,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@scarlett-player/captions",
+  "version": "1.0.0",
+  "description": "Captions Plugin for Scarlett Player - WebVTT subtitles and closed captions",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@scarlett-player/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.6.0",
+    "jsdom": "^24.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0",
+    "@scarlett-player/core": "1.0.0"
+  },
+  "keywords": [
+    "video",
+    "player",
+    "captions",
+    "subtitles",
+    "webvtt",
+    "closed-captions",
+    "scarlett"
+  ],
+  "author": "The Stream Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hackney-Enterprises-Inc/scarlett-player.git",
+    "directory": "packages/plugins/captions"
+  },
+  "bugs": {
+    "url": "https://github.com/Hackney-Enterprises-Inc/scarlett-player/issues"
+  },
+  "homepage": "https://scarlettplayer.com",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage"
+  }
+}