senza-sdk 4.5.2 → 4.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.5.2",
+    "version": "4.5.4",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",

package/src/api.js

@@ -153,12 +153,13 @@ export const envInfo = {
  * @param {ArrayBuffer|string} licenseResponse a license response that was received from the license server to be passed to platform.
  * @param {string} fcid a fcid received with the license request
  * @param {string} sessionId a sessionId received with the license request
- * In case of success licenceResponse is of type @type {ArrayBuffer}
+ * @param {string} playbackId the current playbackId, propagated to platform for session correlation
+ * In case of success licenseResponse is of type @type {ArrayBuffer}
  * In case of error licenseResponse is of type @type {string}
  */
-export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId) {
+export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId) {
     if (window?.senzaSDKImplementation) {
-        return window.senzaSDKImplementation.writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId);
+        return window.senzaSDKImplementation.writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId);
     }
     sdkLogger.error("writeLicenseResponse: window.cefQuery is undefined");
 }

package/src/implementation/api.js

@@ -303,10 +303,11 @@ import "./devHelper.js";
  * @param {ArrayBuffer|string} licenseResponse a license response that was received from the license server to be passed to platform.
  * @param {string} fcid a fcid received with the license request
  * @param {string} sessionId a sessionId received with the license request
- * In case of success licenceResponse is of type @type {ArrayBuffer}
+ * @param {string} playbackId the current playbackId, propagated to platform for session correlation
+ * In case of success licenseResponse is of type @type {ArrayBuffer}
  * In case of error licenseResponse is of type @type {string}
  */
-export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId) {
+export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionId, playbackId) {
 
     if (statusCode >= 200 && statusCode < 300) {
         licenseResponse = window.btoa(String.fromCharCode.apply(null, new Uint8Array(licenseResponse))); // to base64
@@ -316,7 +317,8 @@ export function writeLicenseResponse(statusCode, licenseResponse, fcid, sessionI
         const message = {
             type: "updateLicense",
             sessionId,
-            fcid
+            fcid,
+            playbackId
         };
         message[statusCode >= 200 && statusCode < 300 ? "response" : "error"] = licenseResponse;
         const request = { target: "TC", waitForResponse: false, message: JSON.stringify(message) };

package/src/implementation/overlay.js

@@ -22,6 +22,8 @@ const OVERLAY_CAPTURE_PRESETS = {
 
 const DEFAULT_CAPTURE_PRESET = "default";
 const VALID_QUALITIES = new Set(["low", "mid", "high"]);
+const DEFAULT_AUTO_HIDE_DURATION_SEC = 600;
+const OVERLAY_DURATION_SEC_MAX = 65535;
 
 class Overlay extends OverlayInterface {
     constructor() {
@@ -31,7 +33,8 @@ class Overlay extends OverlayInterface {
         this._configuration = {
             useTransparency: true,
             overlayCapturePreset: DEFAULT_CAPTURE_PRESET,
-            overlayCapturePlan: null
+            overlayCapturePlan: null,
+            autoHideDurationSec: DEFAULT_AUTO_HIDE_DURATION_SEC
         };
         this._activeCapturePlan = OVERLAY_CAPTURE_PRESETS[DEFAULT_CAPTURE_PRESET];
         this._retryGeneration = 0;
@@ -138,6 +141,7 @@ class Overlay extends OverlayInterface {
                     quality,
                     conditional
                 };
+                message.overlayDurationSec = this._configuration.autoHideDurationSec;
                 sdkLogger.log(`Overlay: rendering frame x=${x} y=${y} width=${width} height=${height} fcid=${FCID} (batchId=${batchId}, quality=${quality}, conditional=${conditional})`);
                 const request = { target: "UI-Streamer", waitForResponse: false, message: JSON.stringify(message) };
                 window.cefQuery({
@@ -226,6 +230,16 @@ class Overlay extends OverlayInterface {
             }
         }
 
+        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "autoHideDurationSec")) {
+            const duration = normalizedConfiguration.autoHideDurationSec;
+            if (Number.isInteger(duration) && duration >= 0 && duration <= OVERLAY_DURATION_SEC_MAX) {
+                normalizedConfiguration.autoHideDurationSec = duration;
+            } else {
+                sdkLogger.warn(`Overlay: invalid autoHideDurationSec "${duration}", keeping previous value`);
+                delete normalizedConfiguration.autoHideDurationSec;
+            }
+        }
+
         this._configuration = { ...this._configuration, ...normalizedConfiguration };
         this._activeCapturePlan = this._resolveCapturePlan();
     }

package/src/implementation/remotePlayer.js

@@ -2,6 +2,7 @@
 import { RemotePlayer as RemotePlayerInterface, RemotePlayerError as RemotePlayerErrorInterface, Config } from "../interface/remotePlayer";
 import {
     getFCID,
+    generatePlaybackId,
     isAudioSyncConfigured,
     clearTimer,
     sdkLogger,
@@ -145,6 +146,13 @@ class RemotePlayer extends RemotePlayerInterface {
          * @private
          */
         this._isPlaying = false;
+
+        /**
+         * @type {string}
+         * @description Unique identifier generated on every load attempt. Propagated on all API requests and events.
+         * @private
+         */
+        this._playbackId = "";
     }
 
     /** @private Initialize the remote player
@@ -219,17 +227,33 @@ class RemotePlayer extends RemotePlayerInterface {
 
     }
 
+    /**
+     * @private Returns true and logs an error when an incoming event's playbackId does not match the current one.
+     * @param {Object} detail - The event detail object that may contain a playbackId field.
+     * @param {string} eventType - Name of the incoming event, used in the log message.
+     */
+    _hasPlaybackIdMismatch(detail, eventType) {
+        const incomingId = detail?.playbackId;
+        if (incomingId && this._playbackId && incomingId !== this._playbackId) {
+            sdkLogger.error(`${eventType}: playbackId mismatch. current=${this._playbackId} incoming=${incomingId}. Ignoring.`);
+            return true;
+        }
+        return false;
+    }
+
     /**
      * @private Add event listeners for system events
      */
     _addSenzaEventListeners() {
 
         typeof document !== "undefined" && document.addEventListener("hs/remotePlayerEvent", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/remotePlayerEvent")) return;
             sdkLogger.info("Got hs/remotePlayerEvent event with detail", JSON.stringify(e?.detail));
             this.dispatchEvent(new Event(e?.detail?.eventName));
         });
 
-        typeof document !== "undefined" && document.addEventListener("hs/playbackInfoEvent", () => {
+        typeof document !== "undefined" && document.addEventListener("hs/playbackInfoEvent", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/playbackInfoEvent")) return;
             sdkLogger.info("Got hs/playbackInfoEvent");
             // When attached, the sdk controls the synchronization between the local and remote player.
             if (this._videoElement) {
@@ -243,13 +267,15 @@ class RemotePlayer extends RemotePlayerInterface {
         });
 
         typeof document !== "undefined" && document.addEventListener("hs/playback", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/playback")) return;
             sdkLogger.info("Got hs/playback event with detail", JSON.stringify(e?.detail));
             this._availabilityStartTime = e?.detail?.availabilityStartTime;
             this._updateTracks(e?.detail);
             this.dispatchEvent(new Event("tracksupdate"));
         });
 
-        typeof document !== "undefined" && document.addEventListener("hs/EOS", () => {
+        typeof document !== "undefined" && document.addEventListener("hs/EOS", (e) => {
+            if (this._hasPlaybackIdMismatch(e?.detail, "hs/EOS")) return;
             sdkLogger.info("Got hs/EOS event");
             this._changePlayMode(false);
             this.dispatchEvent(new Event("ended"));
@@ -268,6 +294,7 @@ class RemotePlayer extends RemotePlayerInterface {
             }
         });
         typeof document !== "undefined" && document.addEventListener("hs/senzaPlayerSetRate", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/senzaPlayerSetRate")) return;
             if (!this._videoElement) return;
             if (this._isSeekingByApplication) {
                 sdkLogger.info("Skip senzaPlayerSetRate while seek performed");
@@ -276,6 +303,7 @@ class RemotePlayer extends RemotePlayerInterface {
             this._videoElement.playbackRate = event.detail.rate;
         });
         typeof document !== "undefined" && document.addEventListener("hs/senzaPlayerSetTime", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/senzaPlayerSetTime")) return;
             // For simplicity, make sure we only accept syncing the current time if audio sync is enabled
             if (!this._isAudioSyncEnabled()) return;
             if (this._isSeekingByApplication) {
@@ -291,6 +319,7 @@ class RemotePlayer extends RemotePlayerInterface {
 
 
         typeof document !== "undefined" && document.addEventListener("hs/ERR", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/ERR")) return;
             sdkLogger.info("Got hs/ERR event");
             delete event?.detail?.type; // type is always videoPlaybackEvent, so no need to pass it
             delete event?.detail?.eventCode; // eventCode is always ERR, so no need to pass it
@@ -298,6 +327,7 @@ class RemotePlayer extends RemotePlayerInterface {
         });
 
         typeof document !== "undefined" && document.addEventListener("hs/getLicense", (event) => {
+            if (this._hasPlaybackIdMismatch(event?.detail, "hs/getLicense")) return;
             sdkLogger.info("Got hs/getLicense event");
             const getLicenseEventData = event?.detail;
 
@@ -308,9 +338,10 @@ class RemotePlayer extends RemotePlayerInterface {
             this.licenseRequest = licenseRequest;
             const fcid = getLicenseEventData.fcid;
             const sessionId = getLicenseEventData.sessionId;
+            const playbackId = this._playbackId;
             const licenseRequestEvent = new CustomEvent("license-request", { "detail": { licenseRequest } });
             licenseRequestEvent.writeLicenseResponse = (statusCode, responseBody) => {
-                writeLicenseResponse(statusCode, responseBody, fcid, sessionId);
+                writeLicenseResponse(statusCode, responseBody, fcid, sessionId, playbackId);
             };
             this.dispatchEvent(licenseRequestEvent);
         });
@@ -485,7 +516,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "seek",
                 playbackPosition,
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: waitForResponse, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -544,7 +576,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 fcid: FCID,
                 audioLanguage,
                 subtitlesLanguage,
-                playbackPosition: this.currentTime
+                playbackPosition: this.currentTime,
+                playbackId: this._playbackId
             };
             let waitForResponse = false;
             if (this._remotePlayerApiVersion >= 2) {
@@ -611,7 +644,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 type: "remotePlayer.pause",
                 class: "remotePlayer",
                 action: "pause",
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             if (this._remotePlayerApiVersion >= 2) {
                 message.streamType = this._isAudioSyncEnabled() && isForegroundState ? StreamType.AUDIO : StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE;
@@ -662,7 +696,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "stop",
                 streamType: streamType,
-                fcid: FCID
+                fcid: FCID,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -784,6 +819,7 @@ class RemotePlayer extends RemotePlayerInterface {
             this._abortSeeking = true;
             if (reset) {
                 this._reset();
+                this._playbackId = generatePlaybackId();
             }
             const previousLoadMode = this._loadMode;
             this._changeLoadMode(this.LoadMode.LOADING);
@@ -804,7 +840,8 @@ class RemotePlayer extends RemotePlayerInterface {
                     timeout: this._remotePlayerConfirmationTimeout,
                     autoPlay: false,
                     playbackPosition,
-                    fcid: FCID
+                    fcid: FCID,
+                    playbackId: this._playbackId
                 };
                 if (this._uiAvSyncIntervalMs !== undefined) {
                     message.connectorSettings = message.connectorSettings || {};
@@ -905,7 +942,8 @@ class RemotePlayer extends RemotePlayerInterface {
                     type: "remotePlayer.unload",
                     class: "remotePlayer",
                     action: "unload",
-                    fcid: FCID
+                    fcid: FCID,
+                    playbackId: this._playbackId
                 };
                 const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
                 let timerId = 0;
@@ -918,6 +956,7 @@ class RemotePlayer extends RemotePlayerInterface {
                         logger.withFields({ duration }).log(`unload completed successfully after ${duration} ms`);
                         timerId = clearTimer(timerId);
                         this._reset();
+                        this._playbackId = "";
                         this._changeLoadMode(this.LoadMode.NOT_LOADED);
                         this._loadedUrl = undefined;
                         resolve();
@@ -1240,7 +1279,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "setAudioLanguage",
                 fcid: FCID,
-                language: audioTrackId
+                language: audioTrackId,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -1387,7 +1427,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "setSubtitleLanguage",
                 fcid: FCID,
-                language: textTrackId
+                language: textTrackId,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -1889,7 +1930,8 @@ class RemotePlayer extends RemotePlayerInterface {
                 class: "remotePlayer",
                 action: "screenBlackout",
                 fcid: FCID,
-                blackoutTime
+                blackoutTime,
+                playbackId: this._playbackId
             };
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {

package/src/implementation/utils.js

@@ -14,6 +14,19 @@ export function getFCID() {
     return Math.round(Math.random() * 100000) + "-" + getPlatformInfo().sessionInfo?.connectionId;
 }
 
+export function generatePlaybackId() {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+    const size = 5;
+    let id = "";
+    const bytes = (typeof crypto !== "undefined" && crypto.getRandomValues)
+        ? crypto.getRandomValues(new Uint8Array(size))
+        : Array.from({ length: size }, () => Math.floor(Math.random() * 256));
+    for (let i = 0; i < size; i++) {
+        id += alphabet[bytes[i] & 63];
+    }
+    return id;
+}
+
 export class SenzaError extends Error {
     constructor(code, message) {
         super(message);

package/src/interface/overlay.js

@@ -59,8 +59,8 @@ class Overlay extends EventTarget {
     }
 
     /**
-     * Removes all registered elements, sends a zero-dimension frame to the UI-Streamer,
-     * and deactivates the overlay. After calling removeAllElements(), a new element can be registered.
+     * Removes all registered elements and deactivates the overlay.
+     * After calling removeAllElements(), a new element can be registered.
      *
      * @returns {Promise<boolean>} Resolves to true if successful, rejects with error if failed.
      */
@@ -82,7 +82,7 @@ class Overlay extends EventTarget {
      *
      * @param {Object} configuration - The new configuration to apply.
      * @param {boolean} [configuration.useTransparency=true] - Controls whether the overlay should be rendered with transparency.
-     * When set to `true`, the value is forwarded to UI-Streamer in `displayOverlay` requests.
+     * When set to `true`, the overlay is rendered with transparency.
      * @param {string} [configuration.overlayCapturePreset="default"] - Named capture plan preset:
      * `default` (progressive low→high captures) or `once` (one immediate high-quality conditional step).
      * @param {Array<{quality: "low"|"mid"|"high", conditional: boolean, delay: number}>} [configuration.overlayCapturePlan]
@@ -90,6 +90,9 @@ class Overlay extends EventTarget {
      * the previous step in the batch. Set `conditional` per step (the SDK does not derive it):
      * when `true`, capture only if overlay content changed since the last required (non-conditional)
      * capture in this batch; when `false`, always capture on that step.
+     * @param {number} [configuration.autoHideDurationSec=600] - Client auto-hide duration in seconds.
+     * Defaults to `600` (10 minutes) until configured. Omit the key to keep the current value.
+     * `0` means never auto-hide. Valid range: `0`–`65535`.
      */
     configure(configuration) {
         noop(configuration);

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.5.2";
+export const version = "4.5.4";