senza-sdk 4.5.0 → 4.5.2

package/package.json

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

package/src/implementation/lifecycle.js

@@ -757,6 +757,7 @@ class Lifecycle extends LifecycleInterface {
                         class: "remotePlayer",
                         action: "stop",
                         streamType: remotePlayer._isAudioSyncEnabled() ? StreamType.VIDEO | StreamType.SUBTITLE : StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE,
+                        switchMode: remotePlayer._isAudioSyncEnabled() ? SwitchMode.SEAMLESS : SwitchMode.NON_SEAMLESS,
                         fcid: FCID
                     };
                     let timerId = 0;

package/src/implementation/overlay.js

@@ -1,24 +1,131 @@
 import { Overlay as OverlayInterface } from "../interface/overlay.js";
 import { getFCID, sdkLogger, SenzaError } from "./utils";
 
+/**
+ * Named overlay capture plans. Each step: `{ quality, conditional, delay }`.
+ * Steps run when refresh() is called; `delay` is ms after the previous step in the batch.
+ * `conditional`: 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.
+ * Set per step by the plan author; the SDK does not derive it.
+ */
+const OVERLAY_CAPTURE_PRESETS = {
+    default: [
+        { quality: "low", conditional: false, delay: 0 },
+        { quality: "low", conditional: true, delay: 150 },
+        { quality: "low", conditional: true, delay: 300 },
+        { quality: "high", conditional: false, delay: 600 }
+    ],
+    once: [
+        { quality: "high", conditional: true, delay: 0 }
+    ]
+};
+
+const DEFAULT_CAPTURE_PRESET = "default";
+const VALID_QUALITIES = new Set(["low", "mid", "high"]);
+
 class Overlay extends OverlayInterface {
     constructor() {
         super();
 
         this._element = null;
         this._configuration = {
-            useTransparency: true
+            useTransparency: true,
+            overlayCapturePreset: DEFAULT_CAPTURE_PRESET,
+            overlayCapturePlan: null
         };
+        this._activeCapturePlan = OVERLAY_CAPTURE_PRESETS[DEFAULT_CAPTURE_PRESET];
+        this._retryGeneration = 0;
+        this._planTimerId = null;
+        this._currentBatchId = null;
     }
 
     _isTransparencyEnabled() {
         return this._configuration.useTransparency !== false;
     }
 
-    _sendFrame(x, y, width, height) {
+    _clearPlanTimer() {
+        if (this._planTimerId != null) {
+            clearTimeout(this._planTimerId);
+            this._planTimerId = null;
+        }
+    }
+
+    _clearRetryTimers() {
+        this._retryGeneration++;
+        this._clearPlanTimer();
+    }
+
+    _validateCapturePlan(plan) {
+        if (!Array.isArray(plan) || plan.length === 0) {
+            return false;
+        }
+        for (let i = 0; i < plan.length; i++) {
+            const step = plan[i];
+            if (!step || typeof step !== "object") {
+                return false;
+            }
+            if (!VALID_QUALITIES.has(step.quality)) {
+                return false;
+            }
+            if (typeof step.conditional !== "boolean") {
+                return false;
+            }
+            if (typeof step.delay !== "number" || !Number.isFinite(step.delay) || step.delay < 0) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    _resolveCapturePlan() {
+        if (this._configuration.overlayCapturePlan != null) {
+            return structuredClone(this._configuration.overlayCapturePlan);
+        }
+        const presetName = this._configuration.overlayCapturePreset ?? DEFAULT_CAPTURE_PRESET;
+        const preset = OVERLAY_CAPTURE_PRESETS[presetName];
+        if (!preset) {
+            throw new Error(`Overlay: unknown overlayCapturePreset "${presetName}"`);
+        }
+        return structuredClone(preset);
+    }
+
+    _scheduleCapturePlanFromStep(batchId, plan, generation, startIndex) {
+        const scheduleStep = (index) => {
+            if (this._retryGeneration !== generation) {
+                return;
+            }
+            const step = plan[index];
+            if (!step) {
+                sdkLogger.error(`Overlay: missing capture plan step at index ${index} (plan length ${plan.length})`);
+                return;
+            }
+            this._clearPlanTimer();
+            this._planTimerId = setTimeout(async () => {
+                if (this._retryGeneration !== generation) {
+                    return;
+                }
+                try {
+                    await this._renderFrame(batchId, step, index);
+                } catch (err) {
+                    sdkLogger.error("Overlay: capture plan step error:", err);
+                }
+                if (index + 1 < plan.length && this._retryGeneration === generation) {
+                    scheduleStep(index + 1);
+                }
+            }, step.delay);
+        };
+
+        scheduleStep(startIndex);
+    }
+
+    /**
+     * @param {boolean} conditional - When true, capture only if overlay content changed since
+     * the last required capture in this batch; when false, always capture on this step.
+     */
+    _sendFrame(x, y, width, height, batchId, quality, conditional, stepIndex = 0) {
         if (window.cefQuery) {
             return new Promise((resolve, reject) => {
-                const FCID = getFCID();
+                const FCID = `${stepIndex}-${getFCID()}`;
                 const message = {
                     type: "displayOverlay",
                     x,
@@ -26,8 +133,12 @@ class Overlay extends OverlayInterface {
                     width,
                     height,
                     useTransparency: this._isTransparencyEnabled(),
-                    fcid: FCID
+                    fcid: FCID,
+                    batchId,
+                    quality,
+                    conditional
                 };
+                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({
                     request: JSON.stringify(request),
@@ -44,18 +155,26 @@ class Overlay extends OverlayInterface {
         return Promise.reject("Overlay is not supported if NOT running e2e");
     }
 
-    _renderFrame() {
+    _renderFrame(batchId, captureStep = { quality: "high", conditional: false }, stepIndex = 0) {
         if (!this._element) {
             return Promise.reject("No element configured");
         }
         const rect = this._element.getBoundingClientRect();
         const frame = this._normalizeFrame(rect);
 
-        sdkLogger.log(`Overlay: rendering frame x=${frame.x} y=${frame.y} width=${frame.width} height=${frame.height}`);
-        return this._sendFrame(frame.x, frame.y, frame.width, frame.height).then(() => {
-            const refreshEvent = new Event("refresh");
-            refreshEvent.frame = frame;
-            this.dispatchEvent(refreshEvent);
+        if (frame.width === 0 || frame.height === 0) {
+            sdkLogger.warn(`Overlay: skipping frame with zero size (width=${frame.width}, height=${frame.height})`);
+            return Promise.resolve(false);
+        }
+
+        const id = batchId ?? this._currentBatchId ?? getFCID();
+
+        return this._sendFrame(frame.x, frame.y, frame.width, frame.height, id, captureStep.quality, captureStep.conditional, stepIndex).then(() => {
+            if (!captureStep.conditional) {
+                const refreshEvent = new Event("refresh");
+                refreshEvent.frame = frame;
+                this.dispatchEvent(refreshEvent);
+            }
             return true;
         });
     }
@@ -65,8 +184,8 @@ class Overlay extends OverlayInterface {
 
         const x = Math.round(toFiniteNumber(rect.x));
         const y = Math.round(toFiniteNumber(rect.y));
-        const width = Math.max(1, Math.round(toFiniteNumber(rect.width)));
-        const height = Math.max(1, Math.round(toFiniteNumber(rect.height)));
+        const width = Math.round(toFiniteNumber(rect.width));
+        const height = Math.round(toFiniteNumber(rect.height));
 
         return { x, y, width, height };
     }
@@ -74,11 +193,41 @@ class Overlay extends OverlayInterface {
     _applyConfiguration(configuration) {
         const normalizedConfiguration = { ...configuration };
 
+        if (
+            Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePreset") ||
+            Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePlan")
+        ) {
+            this._clearRetryTimers();
+        }
+
         if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "useTransparency")) {
             normalizedConfiguration.useTransparency = normalizedConfiguration.useTransparency !== false;
         }
 
+        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePreset")) {
+            const preset = normalizedConfiguration.overlayCapturePreset;
+            if (typeof preset === "string" && OVERLAY_CAPTURE_PRESETS[preset]) {
+                normalizedConfiguration.overlayCapturePreset = preset;
+            } else if (preset != null) {
+                sdkLogger.warn(`Overlay: invalid overlayCapturePreset "${preset}", keeping previous preset`);
+                delete normalizedConfiguration.overlayCapturePreset;
+            }
+        }
+
+        if (Object.prototype.hasOwnProperty.call(normalizedConfiguration, "overlayCapturePlan")) {
+            const plan = normalizedConfiguration.overlayCapturePlan;
+            if (plan == null) {
+                normalizedConfiguration.overlayCapturePlan = null;
+            } else if (this._validateCapturePlan(plan)) {
+                normalizedConfiguration.overlayCapturePlan = structuredClone(plan);
+            } else {
+                sdkLogger.warn("Overlay: invalid overlayCapturePlan, keeping previous plan");
+                delete normalizedConfiguration.overlayCapturePlan;
+            }
+        }
+
         this._configuration = { ...this._configuration, ...normalizedConfiguration };
+        this._activeCapturePlan = this._resolveCapturePlan();
     }
 
     async addElement(element) {
@@ -111,6 +260,7 @@ class Overlay extends OverlayInterface {
             return Promise.reject(errorMsg);
         }
 
+        this._clearRetryTimers();
         this._element = null;
 
         return Promise.resolve(true);
@@ -122,11 +272,25 @@ class Overlay extends OverlayInterface {
             sdkLogger.error(errorMsg);
             return Promise.reject(errorMsg);
         }
-        return this._renderFrame();
+        this._clearRetryTimers();
+        this._currentBatchId = getFCID();
+        const batchId = this._currentBatchId;
+        const generation = this._retryGeneration;
+        const plan = this._activeCapturePlan;
+        if (plan[0].delay === 0) {
+            const result = await this._renderFrame(batchId, plan[0], 0);
+            if (result === true && plan.length > 1) {
+                this._scheduleCapturePlanFromStep(batchId, plan, generation, 1);
+            }
+            return result;
+        }
+        this._scheduleCapturePlanFromStep(batchId, plan, generation, 0);
+        return true;
     }
 
     async removeAllElements() {
         sdkLogger.log("Overlay: removing all elements");
+        this._clearRetryTimers();
         this._element = null;
     }
 
@@ -162,6 +326,7 @@ class Overlay extends OverlayInterface {
      * @returns {Promise<boolean>} Resolves to true if successful, rejects with error if failed.
      */
     hideOverlay() {
+        this._clearRetryTimers();
         return this._sendHideOverlay();
     }
 

package/src/implementation/remotePlayer.js

@@ -1021,7 +1021,7 @@ class RemotePlayer extends RemotePlayerInterface {
         }
         // if load in background is supported, play called while state is in background should include all streams
         const backgroundStreamType = this.textTrackVisibility ? (StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE) : (StreamType.AUDIO | StreamType.VIDEO);
-        const streamType = backgroundLoadSupported ? backgroundStreamType : StreamType.AUDIO;
+        const streamType = (backgroundLoadSupported && !isForegroundState) ? backgroundStreamType : StreamType.AUDIO;
 
         return this._play(streamType, switchMode);
     }

package/src/implementation/senzaShakaPlayer.js

@@ -504,6 +504,18 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
 
     }
 
+    _hasActiveTrackForLanguageAndRole(tracks, language, role) {
+        const activeTrack = tracks.find(track => track.active);
+        if (!activeTrack) {
+            return false;
+        }
+
+        if ((!role || activeTrack.roles?.includes(role)) && activeTrack.language === language) {
+            return true;
+        }
+
+        return false;
+    }
 
     _attach(videoElement) {
         this.videoElement = videoElement;
@@ -525,7 +537,10 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
                     this.handleSenzaError(error.code, error.message || "Unknown play error");
                     throw error;
                 });
-                return this._originalPlay.call(this.videoElement);
+                this._originalPlay.call(this.videoElement).catch(error => {
+                    this.handleSenzaError(error.code, error.message || "Unknown play error");
+                });
+                return;
             }
 
             if (this.remotePlayer._isPlaying) {
@@ -620,7 +635,6 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
         return [...new Set(tracks.map(item => item.lang))];
     }
 
-
     selectVariantTrack(track, clearBuffer = false, safeMargin = 0) {
         const audioLang = track.language;
         const audioRole = Array.isArray(track.audioRoles) && track.audioRoles.length > 0
@@ -632,8 +646,11 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
         const apCode = this._getAccessibilityCodeFromPurpose(track.accessibilityPurpose);
         remotePlayer.selectAudioLanguage(audioLang, audioRole, apCode);
 
-        super.selectVariantTrack(track, clearBuffer, safeMargin);
-
+        if (track && !track.active) {
+            super.selectVariantTrack(track, clearBuffer, safeMargin);
+        } else {
+            sdkLogger.log("selectVariantTrack() skipping local Shaka selection because track is already active");
+        }
     }
 
     selectAudioTrack(audioTrack, safeMargin = 0) {
@@ -646,13 +663,24 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
         const apCode = this._getAccessibilityCodeFromPurpose(audioTrack.accessibilityPurpose);
         remotePlayer.selectAudioLanguage(audioLang, role, apCode);
 
-        super.selectAudioTrack(audioTrack, safeMargin);
+        if (audioTrack && !audioTrack.active) {
+            super.selectAudioTrack(audioTrack, safeMargin);
+        } else {
+            sdkLogger.log("selectAudioTrack() skipping local Shaka selection because track is already active");
+        }
     }
 
     selectAudioLanguage(language, role) {
         sdkLogger.log("selectAudioLanguage() Selecting audio language:", language, "with role: ", role);
         remotePlayer.selectAudioLanguage(language, role);
-        super.selectAudioLanguage(language, role);
+
+        const tracks = this.getAudioTracks();
+        sdkLogger.log("selectAudioLanguage: audio tracks", JSON.stringify(tracks), "language", language, "role", role);
+        if (!this._hasActiveTrackForLanguageAndRole(tracks, language, role)) {
+            super.selectAudioLanguage(language, role);
+        } else {
+            sdkLogger.log("selectAudioLanguage() skipping local Shaka selection because language is already active");
+        }
     }
 
     selectTextTrack(textTrack) {
@@ -665,12 +693,22 @@ export class SenzaShakaPlayer extends SenzaShakaInterface {
         const apCode = this._getAccessibilityCodeFromPurpose(textTrack.accessibilityPurpose);
         remotePlayer.selectTextLanguage(textLang, role, apCode);
 
-        super.selectTextTrack(textTrack);
+        if (textTrack && !textTrack.active) {
+            super.selectTextTrack(textTrack);
+        } else {
+            sdkLogger.log("selectTextTrack() skipping local Shaka selection because track is already active");
+        }
     }
     selectTextLanguage(language, role) {
         sdkLogger.log("selectTextLanguage() Selecting text language:", language, "with role: ", role);
         remotePlayer.selectTextLanguage(language, role);
-        super.selectTextLanguage(language, role);
+        const tracks = this.getTextTracks();
+        sdkLogger.log("selectTextLanguage: text tracks", JSON.stringify(tracks));
+        if (!this._hasActiveTrackForLanguageAndRole(tracks, language, role)) {
+            super.selectTextLanguage(language, role);
+        } else {
+            sdkLogger.log("selectTextLanguage() skipping local Shaka selection because language is already active");
+        }
     }
 
     setTextTrackVisibility(visible) {

package/src/interface/overlay.js

@@ -46,6 +46,12 @@ class Overlay extends EventTarget {
      * This is useful when the element's content or position has changed.
      * The overlay must have an element registered before calling refresh.
      *
+     * Runs the configured overlay capture plan after each call. The `default` preset sends
+     * low-quality captures with relative delays, ending with a high-quality capture.
+     * The `once` preset runs one high-quality conditional step immediately.
+     * All steps in one refresh share the same `batchId` (from `getFCID()`). Pending plan
+     * steps are cancelled by a subsequent call to refresh(), hideOverlay(), or removeElement().
+     *
      * @returns {Promise<boolean>} Resolves to true if successful, rejects with error if failed.
      */
     refresh() {
@@ -77,6 +83,13 @@ 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.
+     * @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]
+     * Explicit capture plan; overrides preset. Steps run on refresh(); each step's `delay` is ms after
+     * 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.
      */
     configure(configuration) {
         noop(configuration);

package/src/interface/version.js

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