@gcorevideo/player 2.29.0 → 2.30.1

package/README.md

@@ -81,6 +81,114 @@ See the complete example app on Vercel: <https://github.com/dmitritz/gcore-video
 
 [Example codepen](https://codepen.io/dmitritz/pen/OPLdEab)
 
+## Protected-content streams — automatic token refresh
+
+Gcore protected-content streams embed a security token and expiry timestamp
+directly in the URL path:
+
+```
+https://host/videos/{video-id}/{token}/{expires}/master.m3u8
+```
+
+Once a token expires the CDN returns HTTP 401 for every segment request.
+`TokenRefreshPlugin` handles renewal transparently: it fires a background timer
+before the token expires, calls your `getToken()` function, and rewrites the
+`/{token}/{expires}/` segment in every outgoing hls.js or dash.js request URL —
+playback continues without buffering or interruption.
+
+### Supported playback engines
+
+| Engine | Mechanism | Interruption |
+|---|---|---|
+| **hls.js** | Custom loader rewrites every request URL before XHR `open()` | None |
+| **dash.js** | `addRequestInterceptor` rewrites every request URL | None |
+| **Native `<video>`** (older Safari) | Source reload + seek restore | Brief |
+
+For fully seamless refresh on older Safari, register `example/token-refresh-sw.js`
+as a Service Worker — it intercepts all CDN fetch requests and rewrites the token
+even for native media elements.
+
+### Usage
+
+```ts
+import { Player, TokenRefreshPlugin } from '@gcorevideo/player'
+
+// Register once before creating any player instance.
+Player.registerPlugin(TokenRefreshPlugin)
+
+const player = new Player({
+  sources: [{
+    // The token API returns a ready-to-use URL with the token embedded in the path.
+    // TokenRefreshPlugin reads the initial {token}/{expires} from this URL at startup.
+    source: 'https://host/videos/{id}/{token}/{expires}/master.m3u8',
+    mimeType: 'application/x-mpegURL',
+  }],
+
+  tokenRefresh: {
+    /**
+     * Called automatically ~refreshLeadSeconds before the current token expires.
+     * Must return a Promise resolving to a TokenResponse object.
+     */
+    getToken: () => fetch('https://your-token-api/token').then(r => r.json()),
+
+    /**
+     * Set to true to use IP-bound tokens (token_ip / url_ip).
+     * All CDN requests must then originate from the same IP as the first response.
+     * Default: false.
+     */
+    ipBound: false,
+
+    /**
+     * How many seconds before expiry to pre-fetch the new token.
+     * Rule of thumb: refreshLeadSeconds < tokenLifetime / 2.
+     * Default: 5.
+     */
+    refreshLeadSeconds: 5,
+
+    /** Optional callback fired after each successful token refresh. */
+    onTokenRefreshed(data) {
+      console.log('token refreshed, new expiry:', new Date(data.expires * 1000))
+    },
+  },
+})
+
+player.attachTo(document.getElementById('player'))
+```
+
+### TokenResponse shape
+
+Your `getToken()` function must return an object with this structure:
+
+```ts
+interface TokenResponse {
+  token:     string  // plain (any-IP) token
+  token_ip:  string  // IP-bound token
+  client_ip: string  // client IP the token server observed
+  expires:   number  // Unix timestamp (seconds) when both tokens expire
+  url:       string  // full HLS master URL with plain token in path
+  url_ip:    string  // full HLS master URL with IP-bound token in path
+}
+```
+
+### Pausing and resuming refresh
+
+Use the plugin instance to suspend and resume the refresh cycle at runtime:
+
+```ts
+const plugin = player.getPlugin('token_refresh')
+
+plugin.pause()          // stop the timer; existing token stays active until CDN rejects it
+plugin.resume()         // restart the timer; fetches immediately if token already expired
+console.log(plugin.isPaused)  // → true | false
+```
+
+### Working demo
+
+See [`example/protected-content.html`](../../example/protected-content.html) and
+[`example/protected-content.js`](../../example/protected-content.js) for a fully
+annotated end-to-end integration, including UI feedback, IP-bound token switching,
+a live countdown, and Service Worker integration notes.
+
 ## Documentation
 
 - [API reference](./docs/api/index.md)

package/dist/core.js

@@ -12963,6 +12963,7 @@ class DashPlayback extends BasePlayback {
         this._dash = dash;
         this._dash.initialize();
         if (this.options.dash) {
+            const { requestInterceptor, ...dashSettings } = this.options.dash;
             const settings = $.extend(true, {
                 streaming: {
                     text: {
@@ -12974,8 +12975,11 @@ class DashPlayback extends BasePlayback {
                         // dispatchForManualRendering: true, // TODO only when useNativeSubtitles is not true?
                     },
                 },
-            }, this.options.dash);
+            }, dashSettings);
             this._dash.updateSettings(settings);
+            if (typeof requestInterceptor === 'function') {
+                this._dash.addRequestInterceptor(requestInterceptor);
+            }
         }
         this._dash.attachView(this.el);
         this._dash.setAutoPlay(false);
@@ -49996,6 +50000,48 @@ Hls.defaultConfig = void 0;
 // export const CLAPPR_VERSION: string = process.env.CLAPPR_VERSION || '0.11.3';
 const CLAPPR_VERSION = '0.13.0';
 
+class RangesList {
+    // TODO write an efficient implementation
+    items = [];
+    insert(start, end, value) {
+        const index = this.findIndex((start + end) / 2);
+        this.items.splice(index, 0, [start, end, value]);
+    }
+    find(position) {
+        const index = this.findIndex(position);
+        const item = this.items[index];
+        if (!item || item[0] > position || item[1] < position) {
+            return null;
+        }
+        return item[2];
+    }
+    findIndex(position) {
+        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;
+    }
+}
+
 // Copyright 2014 Globo.com Player authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found on https://github.com/clappr/hlsjs-playback/blob/main/LICENSE
@@ -50005,7 +50051,6 @@ const DEFAULT_RECOVER_ATTEMPTS = 16;
 Events$1.register('PLAYBACK_FRAGMENT_PARSING_METADATA');
 const T$2 = 'playback.hls';
 class HlsPlayback extends BasePlayback {
-    _ccTracksUpdated = false;
     _currentFragment = null;
     _currentLevel = null;
     _durationExcludesAfterLiveSyncPoint = false;
@@ -50030,7 +50075,8 @@ class HlsPlayback extends BasePlayback {
     _timeUpdateTimer = null;
     oncueenter = null;
     oncueexit = null;
-    cues = []; // TODO check the list size and use BST if needed
+    cues = null;
+    cuesByTrack = {};
     currentCueId = null;
     /**
      * @internal
@@ -50227,7 +50273,6 @@ class HlsPlayback extends BasePlayback {
         }
         this._manifestParsed = false;
         // this._ccIsSetup = false
-        this._ccTracksUpdated = false;
         this._setInitialState();
         this._hls.destroy();
         this._hls = null;
@@ -50281,12 +50326,20 @@ class HlsPlayback extends BasePlayback {
         this._hls.on(Events.AUDIO_TRACK_SWITCHED, (evt, data) => this._onAudioTrackSwitched(evt, data));
         this._hls.on(Events.CUES_PARSED, (evt, data) => {
             data.cues?.forEach((cue) => {
-                this.cues.push({
+                if (!this.cues) {
+                    const trackId = this._hls.subtitleTrack;
+                    if (!this.cuesByTrack[trackId]) {
+                        this.cuesByTrack[trackId] = new RangesList();
+                    }
+                    this.cues = this.cuesByTrack[trackId];
+                }
+                const cueInfo = {
                     id: cue.id,
                     start: cue.startTime,
                     end: cue.endTime,
                     text: cue.text,
-                });
+                };
+                this.cues.insert(cue.startTime, cue.endTime, cueInfo);
             });
         });
         this.bindCustomListeners();
@@ -50513,7 +50566,7 @@ class HlsPlayback extends BasePlayback {
         }
     }
     reload() {
-        this.cues = [];
+        this.cues = null;
         this.currentCueId = null;
         this._hls?.startLoad(-1);
     }
@@ -50578,9 +50631,7 @@ class HlsPlayback extends BasePlayback {
     }
     triggerCues() {
         const currentTime = this.getCurrentTime();
-        // const cues = Object.values(this.cues)
-        // TODO build a search tree
-        const cue = this.cues.find((cue) => currentTime >= cue.start && currentTime <= cue.end);
+        const cue = this.cues?.find(currentTime);
         if (cue) {
             this.currentCueId = cue.id;
             this.oncueenter?.(cue);
@@ -50623,20 +50674,14 @@ class HlsPlayback extends BasePlayback {
     destroy() {
         this._stopTimeUpdateTimer();
         this._destroyHLSInstance();
+        this.cues = null;
+        this.cuesByTrack = {};
         return super.destroy();
     }
     _updatePlaybackType(evt, data) {
         const prevPlaybackType = this._playbackType;
         this._playbackType = (data.details.live ? Playback.LIVE : Playback.VOD);
         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();
         }
@@ -50857,7 +50902,10 @@ class HlsPlayback extends BasePlayback {
             return;
         }
         this._hls.subtitleTrack = id;
-        this.cues = [];
+        if (!this.cuesByTrack[id]) {
+            this.cuesByTrack[id] = new RangesList();
+        }
+        this.cues = this.cuesByTrack[id];
     }
     /**
      * @override
@@ -50866,7 +50914,7 @@ class HlsPlayback extends BasePlayback {
         return this.getTextTracks();
     }
     getTextTracks() {
-        return this._hls?.subtitleTracks.map((t) => ({
+        return (this._hls?.subtitleTracks.map((t) => ({
             id: t.id,
             name: t.name,
             track: {
@@ -50874,7 +50922,7 @@ class HlsPlayback extends BasePlayback {
                 label: t.name,
                 language: t.lang,
             },
-        })) || [];
+        })) || []);
     }
 }
 HlsPlayback.canPlay = function (resource, mimeType) {
@@ -51206,6 +51254,17 @@ 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) {
+        return this.player?.core.getPlugin(name) ?? null;
+    }
     /**
      * Mutes the sound of the video.
      */
@@ -51477,7 +51536,7 @@ class Player {
     }
 }
 
-var version$1 = "2.29.0";
+var version$1 = "2.30.1";
 
 var packages = {
 	"node_modules/@clappr/core": {