@gcorevideo/player 2.29.0 → 2.30.1

package/lib/plugins/token-refresh/TokenRefreshPlugin.js

@@ -0,0 +1,318 @@
+import { $, CorePlugin, Events } from '@clappr/core';
+import HLSJS from 'hls.js';
+import { trace } from '@gcorevideo/utils';
+import { CLAPPR_VERSION } from '../../build.js';
+const T = 'plugins.token_refresh';
+/**
+ * Matches the `/{token}/{expires}/` segment in a Gcore protected-content URL.
+ * Token is base64url (letters, digits, `-`, `_`); expires is a ≥10-digit Unix timestamp.
+ */
+const TOKEN_SEGMENT_RE = /\/([A-Za-z0-9_-]{6,})\/(1\d{9,})\//;
+function extractTokenState(url) {
+    const m = url.match(TOKEN_SEGMENT_RE);
+    if (!m)
+        return null;
+    return { token: m[1], expires: parseInt(m[2], 10) };
+}
+/** Replaces the exact `/{oldToken}/{oldExpires}/` segment in a URL. */
+function rewriteUrl(url, from, to) {
+    const oldPart = `/${from.token}/${from.expires}/`;
+    const newPart = `/${to.token}/${to.expires}/`;
+    return url.includes(oldPart) ? url.replace(oldPart, newPart) : url;
+}
+/**
+ * Normalises a URL by removing the `/{token}/{expires}/` segment so two URLs
+ * for the same stream with different token pairs compare equal.
+ * Returns `null` for unparseable input.
+ */
+function streamKey(url) {
+    try {
+        const u = new URL(url);
+        return u.origin + u.pathname.replace(TOKEN_SEGMENT_RE, '/');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Returns a custom hls.js loader class that transparently rewrites the
+ * token/expires path segments in every request URL.
+ *
+ * The returned class extends the default hls.js XhrLoader so all native
+ * hls.js behaviour (retry, timeout, range requests …) is preserved.
+ */
+function createTokenRewritingLoader(getOriginal, getCurrent) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const DefaultLoader = HLSJS.DefaultConfig.loader;
+    return class TokenRewritingLoader extends DefaultLoader {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        load(context, config, callbacks) {
+            const original = getOriginal();
+            const current = getCurrent();
+            if (original && current && context.url) {
+                context.url = rewriteUrl(context.url, original, current);
+            }
+            super.load(context, config, callbacks);
+        }
+    };
+}
+/**
+ * `PLUGIN` — automatic token refresh for Gcore protected-content streams.
+ *
+ * Supports all three playback engines:
+ *
+ * | Engine | Mechanism | Interruption |
+ * |--------|-----------|--------------|
+ * | **hls.js** | Custom loader rewrites every request URL | None |
+ * | **dash.js** | `addRequestInterceptor` rewrites every request URL | None |
+ * | **Native `<video>`** (Safari ≤ iOS 14.4) | Source reload + seek restore | Brief |
+ *
+ * @public
+ * @remarks
+ * Register the plugin once before creating any player instance:
+ * ```ts
+ * import { Player, TokenRefreshPlugin } from '@gcorevideo/player'
+ * Player.registerPlugin(TokenRefreshPlugin)
+ * ```
+ *
+ * Then pass `tokenRefresh` in `PlayerConfig`:
+ * ```ts
+ * const player = new Player({
+ *   sources: [{ source: initialUrl, mimeType: 'application/x-mpegURL' }],
+ *   tokenRefresh: {
+ *     getToken: () => fetch('https://…/token').then(r => r.json()),
+ *     ipBound: false,
+ *     refreshLeadSeconds: 5,
+ *     onTokenRefreshed: (data) => console.log('new token expires', data.expires),
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * Safari native — opt-in Service Worker for fully seamless refresh:
+ * ```js
+ * // Register token-refresh-sw.js (see example/ directory)
+ * // and omit tokenRefresh config — the SW handles rewriting.
+ * ```
+ */
+export class TokenRefreshPlugin extends CorePlugin {
+    /** @internal */
+    static get type() {
+        return 'core';
+    }
+    /** @internal */
+    get name() {
+        return 'token_refresh';
+    }
+    /** @internal */
+    get supportedVersion() {
+        return { min: CLAPPR_VERSION };
+    }
+    /** Token state extracted from the currently-managed source URL */
+    originalState = null;
+    /** Latest token state (updated after each refresh) */
+    currentState = null;
+    /** Scheduled refresh timer handle */
+    refreshTimer = null;
+    /** Playback time (seconds) to restore after a native-video source reload */
+    savedPosition = null;
+    /** True when using native HTML5 Video playback (no request interception) */
+    isNativePlayback = false;
+    /** Set in destroy(); short-circuits late timer callbacks and getToken() resolutions */
+    destroyed = false;
+    /** @internal */
+    bindEvents() {
+        this.listenTo(this.core, Events.CORE_CONTAINERS_CREATED, this.onContainersCreated);
+    }
+    /** @internal */
+    destroy() {
+        this.destroyed = true;
+        this.clearTimer();
+        super.destroy();
+    }
+    onContainersCreated() {
+        const container = this.core.containers[0];
+        if (!container)
+            return;
+        const playbackName = container.playback.name;
+        const src = container.playback.options?.src ?? '';
+        trace(`${T} onContainersCreated`, { playbackName, src: src.slice(0, 80) });
+        this.isNativePlayback = playbackName !== 'hls' && playbackName !== 'dash';
+        const state = extractTokenState(src);
+        if (!state) {
+            // Active source has no token pattern — drop any refresh state we were
+            // holding for a previous stream (e.g. SourceController rotated away).
+            if (this.originalState) {
+                trace(`${T} active source has no token pattern — clearing refresh state`);
+                this.clearTimer();
+                this.originalState = null;
+                this.currentState = null;
+            }
+            return;
+        }
+        // Adopt the new token state if this is the first source we see, or if
+        // the stream has changed (SourceController rotated, consumer called
+        // player.load() with a different stream, or the plugin itself reloaded
+        // with a refreshed URL in the native path).
+        const isNewStream = !this.originalState ||
+            state.token !== this.originalState.token ||
+            state.expires !== this.originalState.expires;
+        if (isNewStream) {
+            trace(`${T} adopting source token state`, {
+                token: state.token.slice(0, 8) + '…',
+                expires: new Date(state.expires * 1000).toISOString(),
+            });
+            this.originalState = { ...state };
+            this.currentState = { ...state };
+            this.scheduleRefresh();
+        }
+        // Inject the appropriate interception mechanism for this playback engine.
+        switch (playbackName) {
+            case 'hls':
+                this.injectHlsLoader(container);
+                break;
+            case 'dash':
+                this.injectDashInterceptor(container);
+                break;
+            default:
+                // Native HTML5 Video — no request hooks available.
+                // Seek restore after a token-triggered reload.
+                this.listenToOnce(this.core, Events.CORE_ACTIVE_CONTAINER_CHANGED, this.onActiveContainerChangedForNative);
+                break;
+        }
+    }
+    injectHlsLoader(container) {
+        const getOriginal = () => this.originalState;
+        const getCurrent = () => this.currentState;
+        const TokenLoader = createTokenRewritingLoader(getOriginal, getCurrent);
+        $.extend(true, container.playback.options, {
+            playback: {
+                hlsjsConfig: {
+                    loader: TokenLoader,
+                },
+            },
+        });
+        trace(`${T} HLS custom loader injected`);
+    }
+    injectDashInterceptor(container) {
+        $.extend(true, container.playback.options, {
+            dash: {
+                requestInterceptor: (request) => {
+                    if (this.originalState && this.currentState) {
+                        request.url = rewriteUrl(request.url, this.originalState, this.currentState);
+                    }
+                    return Promise.resolve(request);
+                },
+            },
+        });
+        trace(`${T} DASH request interceptor injected`);
+    }
+    async reloadNativeSource(data) {
+        const container = this.core.activeContainer;
+        const playback = container?.playback;
+        if (!playback)
+            return;
+        // SourceController (or any other actor) may have switched the active
+        // playback to hls/dash while getToken() was in flight. Those engines
+        // have their own request-interception path; a native reload would
+        // undo the switch.
+        if (playback.name === 'hls' || playback.name === 'dash') {
+            trace(`${T} skipping native reload — active playback is ${playback.name}`);
+            return;
+        }
+        if (!this.isNativePlayback) {
+            trace(`${T} skipping native reload — no longer in native playback mode`);
+            return;
+        }
+        // Verify the URL we're about to load belongs to the same stream that's
+        // currently active. If SourceController rotated to a different stream
+        // during the getToken() await, the refreshed URL would silently swap
+        // us back, undoing SourceController's decision.
+        const currentSrc = playback.options?.src ?? '';
+        const newUrl = this.opts.ipBound ? data.url_ip : data.url;
+        const activeKey = streamKey(currentSrc);
+        const nextKey = streamKey(newUrl);
+        if (!activeKey || !nextKey || activeKey !== nextKey) {
+            trace(`${T} skipping native reload — active source differs from refresh URL`, {
+                activeKey,
+                nextKey,
+            });
+            return;
+        }
+        // Capture current playback position before tearing down the container.
+        const mediaEl = playback.el;
+        const currentTime = mediaEl?.currentTime ?? 0;
+        this.savedPosition = currentTime > 0 ? currentTime : null;
+        trace(`${T} native reload`, { newUrl: newUrl.slice(0, 80), savedPosition: this.savedPosition });
+        // core.load() destroys and recreates all containers.
+        this.core.load([{ source: newUrl, mimeType: this.core.options.mimeType ?? 'application/x-mpegURL' }]);
+    }
+    onActiveContainerChangedForNative() {
+        if (this.savedPosition === null)
+            return;
+        const pos = this.savedPosition;
+        this.savedPosition = null;
+        // Wait for the new container to be fully ready before seeking.
+        const container = this.core.activeContainer;
+        if (!container)
+            return;
+        this.listenToOnce(container, Events.CONTAINER_READY, () => {
+            trace(`${T} native: restoring position`, { pos });
+            container.seek(pos);
+            container.play();
+        });
+    }
+    scheduleRefresh() {
+        this.clearTimer();
+        if (this.destroyed || !this.currentState)
+            return;
+        const leadMs = (this.opts.refreshLeadSeconds ?? 5) * 1000;
+        const msUntilRefresh = this.currentState.expires * 1000 - Date.now() - leadMs;
+        trace(`${T} next refresh in`, {
+            seconds: Math.round(msUntilRefresh / 1000),
+            expires: new Date(this.currentState.expires * 1000).toISOString(),
+        });
+        this.refreshTimer = setTimeout(() => this.performRefresh(), Math.max(msUntilRefresh, 1000));
+    }
+    async performRefresh() {
+        trace(`${T} fetching new token`);
+        try {
+            const data = await this.opts.getToken();
+            // Plugin may have been destroyed while getToken() was in flight; drop the result.
+            if (this.destroyed)
+                return;
+            const newToken = this.opts.ipBound ? data.token_ip : data.token;
+            const newState = { token: newToken, expires: data.expires };
+            if (this.isNativePlayback) {
+                // Must reload source because the <video> element has no request hook.
+                await this.reloadNativeSource(data);
+            }
+            // originalState is never changed after init — it holds the token that was
+            // baked into every URL in the initial manifest. hls.js/dash.js always
+            // produces request URLs based on that manifest, so every segment URL
+            // still contains the original token regardless of how many refreshes
+            // have already happened. The loader replaces original→current on each
+            // request, so updating only currentState is sufficient.
+            this.currentState = newState;
+            this.opts.onTokenRefreshed?.(data);
+            trace(`${T} token refreshed`, {
+                token: newToken.slice(0, 8) + '…',
+                expires: new Date(data.expires * 1000).toISOString(),
+            });
+        }
+        catch (err) {
+            trace(`${T} token refresh failed`, { err });
+        }
+        // Always reschedule, even after an error (will retry near next expiry).
+        this.scheduleRefresh();
+    }
+    get opts() {
+        return this.options.tokenRefresh;
+    }
+    clearTimer() {
+        if (this.refreshTimer !== null) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+}

package/lib/plugins/token-refresh/index.d.ts

@@ -0,0 +1,2 @@
+export { TokenRefreshPlugin, type TokenRefreshOptions, type TokenResponse, } from './TokenRefreshPlugin.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/plugins/token-refresh/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/plugins/token-refresh/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,yBAAyB,CAAA"}

package/lib/plugins/token-refresh/index.js

@@ -0,0 +1 @@
+export { TokenRefreshPlugin, } from './TokenRefreshPlugin.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcorevideo/player",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "description": "Gcore JavaScript video player",
   "main": "dist/index.js",
   "type": "module",

package/src/Player.ts

@@ -278,6 +278,18 @@ export class Player {
     this.player?.load(ms, ms[0].mimeType ?? '')
   }
 
+  /**
+   * Returns a registered core plugin instance by name, or `null` if not found.
+   *
+   * @example
+   * ```ts
+   * const tokenRefresh = player.getPlugin('token_refresh') as TokenRefreshPlugin | null
+   * ```
+   */
+  getPlugin(name: string) {
+    return this.player?.core.getPlugin(name) ?? null
+  }
+
   /**
    * Mutes the sound of the video.
    */

package/src/index.plugins.ts

@@ -36,4 +36,5 @@ export * from './plugins/telemetry/Telemetry.js'
 export * from './plugins/thumbnails/Thumbnails.js'
 // _ vast-ads
 // _ video360
+export * from './plugins/token-refresh/index.js'
 export * from './plugins/volume-fade/VolumeFade.js'

package/src/playback/dash-playback/DashPlayback.ts

@@ -243,6 +243,7 @@ export default class DashPlayback extends BasePlayback {
     this._dash.initialize()
 
     if (this.options.dash) {
+      const { requestInterceptor, ...dashSettings } = this.options.dash as Record<string, unknown>
       const settings = $.extend(
         true,
         {
@@ -257,9 +258,13 @@ export default class DashPlayback extends BasePlayback {
             },
           },
         },
-        this.options.dash,
+        dashSettings,
       )
       this._dash.updateSettings(settings)
+
+      if (typeof requestInterceptor === 'function') {
+        this._dash.addRequestInterceptor(requestInterceptor as Parameters<typeof this._dash.addRequestInterceptor>[0])
+      }
     }
 
     this._dash.attachView(this.el as HTMLMediaElement)

package/src/playback/hls-playback/HlsPlayback.ts

@@ -35,6 +35,7 @@ import { BasePlayback } from '../BasePlayback.js'
 import { CLAPPR_VERSION } from '../../build.js'
 import { AudioTrack } from '@clappr/core/types/base/playback/playback.js'
 import { VTTCueInfo } from '../types.js'
+import { RangesList } from './RangesList.js'
 
 const { now } = Utils
 
@@ -70,8 +71,6 @@ type CustomListener = {
 }
 
 export default class HlsPlayback extends BasePlayback {
-  private _ccTracksUpdated = false
-
   private _currentFragment: Fragment | null = null
 
   private _currentLevel: number | null = null
@@ -120,7 +119,9 @@ export default class HlsPlayback extends BasePlayback {
 
   oncueexit: ((e: { id: string }) => void) | null = null
 
-  private cues: VTTCueInfo[] = [] // TODO check the list size and use BST if needed
+  private cues: RangesList<VTTCueInfo> | null = null
+
+  private cuesByTrack: Record<number, RangesList<VTTCueInfo>> = {}
 
   private currentCueId: string | null = null
 
@@ -310,7 +311,7 @@ export default class HlsPlayback extends BasePlayback {
     // added/removed every 5.
     this._extrapolatedWindowNumSegments =
       !this.options.playback ||
-        typeof this.options.playback.extrapolatedWindowNumSegments === 'undefined'
+      typeof this.options.playback.extrapolatedWindowNumSegments === 'undefined'
         ? 2
         : this.options.playback.extrapolatedWindowNumSegments
 
@@ -362,7 +363,6 @@ export default class HlsPlayback extends BasePlayback {
     }
     this._manifestParsed = false
     // this._ccIsSetup = false
-    this._ccTracksUpdated = false
     this._setInitialState()
     this._hls.destroy()
     this._hls = null
@@ -436,9 +436,7 @@ export default class HlsPlayback extends BasePlayback {
       (evt: HlsEvents.LEVEL_SWITCHED, data: { level: number }) =>
         this._onLevelSwitched(evt, data),
     )
-    this._hls.on(HlsEvents.ERROR, (evt, data) =>
-      this._onHLSJSError(evt, data),
-    )
+    this._hls.on(HlsEvents.ERROR, (evt, data) => this._onHLSJSError(evt, data))
     this._hls.on(HlsEvents.AUDIO_TRACKS_UPDATED, (evt, data) =>
       this._onAudioTracksUpdated(evt, data),
     )
@@ -447,12 +445,20 @@ export default class HlsPlayback extends BasePlayback {
     )
     this._hls.on(HlsEvents.CUES_PARSED, (evt, data) => {
       data.cues?.forEach((cue: any) => {
-        this.cues.push({
+        if (!this.cues) {
+          const trackId = this._hls!.subtitleTrack
+          if (!this.cuesByTrack[trackId]) {
+            this.cuesByTrack[trackId] = new RangesList<VTTCueInfo>()
+          }
+          this.cues = this.cuesByTrack[trackId]
+        }
+        const cueInfo = {
           id: cue.id,
           start: cue.startTime,
           end: cue.endTime,
           text: cue.text,
-        } as VTTCueInfo)
+        } as VTTCueInfo
+        this.cues.insert(cue.startTime, cue.endTime, cueInfo)
       })
     })
     this.bindCustomListeners()
@@ -514,7 +520,7 @@ export default class HlsPlayback extends BasePlayback {
   }
 
   // this playback manages the src on the video element itself
-  protected override _setupSrc(srcUrl: string) { } // eslint-disable-line no-unused-vars
+  protected override _setupSrc(srcUrl: string) {} // eslint-disable-line no-unused-vars
 
   private _startTimeUpdateTimer() {
     if (this._timeUpdateTimer) {
@@ -579,7 +585,7 @@ export default class HlsPlayback extends BasePlayback {
     // assume live if time within 3 seconds of end of stream
     this.dvrEnabled && this._updateDvr(time < this.getDuration() - 3)
     time += this._startTime
-      ; (this.el as HTMLMediaElement).currentTime = time
+    ;(this.el as HTMLMediaElement).currentTime = time
 
     this.triggerCues()
   }
@@ -719,7 +725,7 @@ export default class HlsPlayback extends BasePlayback {
   }
 
   private reload() {
-    this.cues = []
+    this.cues = null
     this.currentCueId = null
     this._hls?.startLoad(-1)
   }
@@ -777,12 +783,12 @@ export default class HlsPlayback extends BasePlayback {
           start: Math.max(
             0,
             (this.el as HTMLMediaElement).buffered.start(i) -
-            this._playableRegionStartTime,
+              this._playableRegionStartTime,
           ),
           end: Math.max(
             0,
             (this.el as HTMLMediaElement).buffered.end(i) -
-            this._playableRegionStartTime,
+              this._playableRegionStartTime,
           ),
         },
       ]
@@ -804,9 +810,7 @@ export default class HlsPlayback extends BasePlayback {
 
   private triggerCues() {
     const currentTime = this.getCurrentTime()
-    // const cues = Object.values(this.cues)
-    // TODO build a search tree
-    const cue = this.cues.find((cue: VTTCueInfo) => currentTime >= cue.start && currentTime <= cue.end)
+    const cue = this.cues?.find(currentTime)
     if (cue) {
       this.currentCueId = cue.id
       this.oncueenter?.(cue)
@@ -836,7 +840,7 @@ export default class HlsPlayback extends BasePlayback {
     if (!this._hls) {
       return
     }
-    ; (this.el as HTMLMediaElement).pause()
+    ;(this.el as HTMLMediaElement).pause()
     if (this.dvrEnabled) {
       this._updateDvr(true)
     }
@@ -853,6 +857,8 @@ export default class HlsPlayback extends BasePlayback {
   destroy() {
     this._stopTimeUpdateTimer()
     this._destroyHLSInstance()
+    this.cues = null
+    this.cuesByTrack = {}
     return super.destroy()
   }
 
@@ -865,14 +871,6 @@ export default class HlsPlayback extends BasePlayback {
       data.details.live ? Playback.LIVE : Playback.VOD
     ) as PlaybackType
     this._onLevelUpdated(evt, data)
-    // Live stream subtitle tracks detection hack (may not immediately available)
-    // if (
-    //   this._ccTracksUpdated &&
-    //   this._playbackType === Playback.LIVE &&
-    //   this.hasClosedCaptionsTracks
-    // ) {
-    //   this._onSubtitleLoaded()
-    // }
     if (prevPlaybackType !== this._playbackType) {
       this._updateSettings()
     }
@@ -952,7 +950,7 @@ export default class HlsPlayback extends BasePlayback {
               Math.max(
                 fragments[0].start,
                 previousPlayableRegionStartTime +
-                this._extrapolatedWindowDuration,
+                  this._extrapolatedWindowDuration,
               ) * 1000,
           }
         }
@@ -1139,7 +1137,10 @@ export default class HlsPlayback extends BasePlayback {
       return
     }
     this._hls!.subtitleTrack = id
-    this.cues = []
+    if (!this.cuesByTrack[id]) {
+      this.cuesByTrack[id] = new RangesList<VTTCueInfo>()
+    }
+    this.cues = this.cuesByTrack[id]
   }
 
   /**
@@ -1150,15 +1151,17 @@ export default class HlsPlayback extends BasePlayback {
   }
 
   getTextTracks() {
-    return this._hls?.subtitleTracks.map((t: MediaPlaylist) => ({
-      id: t.id,
-      name: t.name,
-      track: {
+    return (
+      this._hls?.subtitleTracks.map((t: MediaPlaylist) => ({
         id: t.id,
-        label: t.name,
-        language: t.lang,
-      },
-    })) || []
+        name: t.name,
+        track: {
+          id: t.id,
+          label: t.name,
+          language: t.lang,
+        },
+      })) || []
+    )
   }
 }
 

package/src/playback/hls-playback/RangesList.ts

@@ -0,0 +1,45 @@
+
+export class RangesList<T> {
+  // TODO write an efficient implementation
+  private items: Array<[number, number, T]> = [];
+
+  insert(start: number, end: number, value: T) {
+    const index = this.findIndex((start + end) / 2);
+    this.items.splice(index, 0, [start, end, value]);
+  }
+
+  find(position: number): T | null {
+    const index = this.findIndex(position);
+    const item = this.items[index];
+    if (!item || item[0] > position || item[1] < position) {
+      return null;
+    }
+    return item[2];
+  }
+
+  private findIndex(position: number): number {
+    let low = 0;
+    let high = this.items.length;
+    let index = 0;
+    while (low < high) {
+      index = low + Math.floor((high - low) / 2);
+      const item = this.items[index];
+      if (item[0] > position) {
+        if (index === low) {
+          return index
+        }
+        high = index;
+        continue;
+      }
+      if (item[1] <= position) {
+        if (index === high - 1) {
+          return index + 1
+        }
+        low = index + 1;
+        continue;
+      }
+      break;
+    }
+    return index;
+  }
+}