senza-sdk 4.4.4 → 4.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.4.4",
+    "version": "4.4.5",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",
@@ -23,17 +23,18 @@
         "version:output": "echo 'export const version = \"'$npm_package_version'\";' > src/interface/version.js"
     },
     "devDependencies": {
-        "@babel/cli": "^7.13.16",
-        "@babel/core": "7.18.6",
-        "@babel/plugin-transform-modules-commonjs": "^7.16.8",
-        "@babel/preset-env": "^7.14.1",
+        "@babel/cli": "^7.22.0",
+        "@babel/core": "^7.22.0",
+        "@babel/plugin-transform-modules-commonjs": "^7.22.0",
+        "@babel/preset-env": "^7.22.0",
         "@eslint/eslintrc": "^3.3.0",
         "@eslint/js": "^9.22.0",
-        "babel-jest": "^27.5.1",
+        "babel-jest": "^30.2.0",
         "eslint": "^9.22.0",
         "eslint-plugin-jest": "^28.11.0",
         "globals": "^16.0.0",
-        "jest": "^27.5.1",
+        "jest": "^30.2.0",
+        "jest-environment-jsdom" : "^30.2.0",
         "jsdoc-to-markdown": "^7.1.1",
         "webpack": "^5.72.1",
         "webpack-cli": "^5.1.4"

package/src/implementation/api.js

@@ -6,6 +6,7 @@ import { remotePlayer } from "./remotePlayer.js";
 import { deviceManager } from "./deviceManager.js";
 import { displayManager } from "./displayManager.js";
 import { messageManager } from "./messageManager.js";
+import { backgroundRenderControl } from "./backgroundRenderControl.js";
 
 export { remotePlayer };
 export { lifecycle };
@@ -141,6 +142,7 @@ export async function init(interfaceApiVersion, showSequenceFunc, initSequenceFu
         await remotePlayer._init(sessionInfoObj, triggerEvent);
         alarmManager._init();
         messageManager._init();
+        backgroundRenderControl._init();
         await displayManager._init();
         sdkLogger.log("All submodules initialized");
 

package/src/implementation/backgroundRenderControl.js

@@ -0,0 +1,113 @@
+import { lifecycle } from "./lifecycle.js";
+import { sdkLogger } from "./utils.js";
+import { sessionInfo } from "./SessionInfo";
+
+/**
+ * Internal background render control.
+ * Listens to lifecycle state changes and disables animation / video rendering when in background mode.
+ * Specifically it pauses CSS animations and hides video elements to reduce CPU/GPU load
+ *
+ * For remote-gpu deployments this reduces the CPU use in background mode from 6 cores to 0.4 cores.
+ *
+ * Extra CPU can be saved by also overriding requestAnimationFrame and slowing down time.
+ * This has the effect of ensuring the segments are downloaded at a slower pace
+ * - or not at all if you actually pause video, but these may have more complicated state and audio sync issues.
+ * Either way if you slow the decoding speed then we save more CPU by not doing as much SW video decoding,
+ * but the bulk is saved by the hidden video elements.
+ * See comments on https://jira01.engit.synamedia.com/browse/HSDEV-16827 for more about a PoC / spike that did this.
+ *
+ * As it stands, the current implementation that gets us 0.4 cores in background mode for remote-gpu is a good compromise of complexity vs benefit.
+ * It also roughly matches GPU mode background CPU use (maybe slightly better).
+ * GPU mode with this feature enabled (from my testing) saves about 0.15 cores ~0.45 -> ~0.30 cores
+ *
+ * This module uses the following settings:
+ * {
+ *   "ui-streamer": {
+ *     "throttleRenderingInBackground": {
+ *       "enabled": true,            // enable or disable the feature
+ *     }
+ *   }
+ * }
+ */
+class BackgroundRenderControl {
+
+    /** initialised
+     * @type {boolean}
+     * @private
+     * Whether the instance has been initialized.
+     */
+    _initialized = false;
+
+    /**
+     * @type {boolean}
+     * @private
+     * Whether render control is enabled.
+     */
+    _enabled = false;
+
+    /**
+     * @type {boolean}
+     * @private
+     * Whether rendering is currently active.
+     */
+    _active = true;
+
+    /** @type {string|null}
+     * @private
+     * Stores the last known lifecycle state.
+     */
+    _lastState = null;
+
+    /** @type {Function}
+     * @private
+     * Event listener for lifecycle state changes.
+     */
+    _listener = (e) => this._handleStateChange(e.state);
+
+    _init() {
+        if (this._initialized) return;
+        this._enabled = sessionInfo?.sessionInfoObj.settings?.["ui-streamer"]?.throttleRenderingInBackground?.enabled ?? false;
+        sdkLogger.log(`Initializing BackgroundRenderControl: enabled=${this._enabled}`);
+        if (!this._enabled) return;
+        this._lastState = lifecycle.state;
+        lifecycle.addEventListener("onstatechange", this._listener);
+        this._initialized = true;
+    }
+
+    _handleStateChange(state) {
+        if (!this._enabled) return;
+        if (state === this._lastState) return;
+        this._lastState = state;
+        try {
+            if (state === lifecycle.UiState.FOREGROUND) this._onForeground();
+            else if (state === lifecycle.UiState.BACKGROUND) this._onBackground();
+        } catch (err) {
+            sdkLogger.error("BackgroundRenderControl state handling error", err);
+        }
+    }
+
+    _onForeground() {
+        if (this._active) return;
+        sdkLogger.log("BackgroundRenderControl resume rendering");
+        this._active = true;
+        const style = document.getElementById("hs-sdk-bg-render-styles");
+        if (style) style.remove();
+    }
+
+    _onBackground() {
+        if (!this._active) return;
+        sdkLogger.log("BackgroundRenderControl throttle rendering");
+        this._active = false;
+        if (!document.getElementById("hs-sdk-bg-render-styles")) {
+            const style = document.createElement("style");
+            style.id = "hs-sdk-bg-render-styles";
+            style.textContent = `
+            * { animation-play-state: paused !important; transition: none !important; scroll-behavior: auto !important; }
+            canvas, video, img { visibility: hidden !important; }
+            `;
+            document.head.appendChild(style);
+        }
+    }
+}
+
+export const backgroundRenderControl = new BackgroundRenderControl();

package/src/implementation/lifecycle.js

@@ -62,6 +62,12 @@ class Lifecycle extends LifecycleInterface {
         this._autoBackgroundOnUIDelay = DEFAULT_AUTO_BACKGROUND_UI_DELAY;
     }
 
+    // List of event types that should use the _eventManager
+    static _waitForListenersEvents = [
+        "userdisconnected","beforestatechange"
+        // Add more event types here if needed in the future
+    ];
+
     /**
      * @private Initialize the lifecycle
      * @param {Object} uiStreamerSettings - UI-streamer portion of the settings taken from session info
@@ -177,7 +183,7 @@ class Lifecycle extends LifecycleInterface {
             const event = new Event("onstatechange");
             event.state = e.detail;
             this._state = event.state;
-            if (this._isAutoBackgroundEnabled() && this.state === this.UiState.FOREGROUND) {
+            if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning()) {
                 this._startCountdown();
             }
             this.dispatchEvent(event);
@@ -213,7 +219,7 @@ class Lifecycle extends LifecycleInterface {
 
         // Add playModeChange listener
         remotePlayer.addEventListener("playModeChange", (event) => {
-            if (this._isAutoBackgroundEnabled() && this.state === this.UiState.FOREGROUND) {
+            if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning()) {
                 sdkLogger.log("Resetting auto background timer due to play mode change", event.detail.isPlaying);
                 this._startCountdown(event.detail.isPlaying);
             }
@@ -221,6 +227,14 @@ class Lifecycle extends LifecycleInterface {
         sdkLogger.log("[Lifecycle] Added event listeners for system events");
     }
 
+    /**
+     * @private Checks if the UI is in foreground or transitioning to foreground.
+     * @returns {boolean}
+     */
+    _isForegroundOrTransitioning() {
+        return this._state === this.UiState.FOREGROUND || this._state === this.UiState.IN_TRANSITION_TO_FOREGROUND;
+    }
+
     /**
      * @private Checks if auto background is enabled including overrides.
      * @returns {boolean}
@@ -284,7 +298,7 @@ class Lifecycle extends LifecycleInterface {
             }
 
             // Start or stop countdown based on new configuration
-            if (this._isAutoBackgroundEnabled()) {
+            if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning()) {
                 this._startCountdown();
             } else {
                 this._stopCountdown();
@@ -364,7 +378,7 @@ class Lifecycle extends LifecycleInterface {
 
     set autoBackground(enabled) {
         this._autoBackground = enabled;
-        if (this._isAutoBackgroundEnabled()) {
+        if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning()) {
             this._startCountdown();
         } else {
             this._stopCountdown();
@@ -377,7 +391,7 @@ class Lifecycle extends LifecycleInterface {
 
     set autoBackgroundDelay(delay) {
         this._autoBackgroundOnVideoDelay = delay;
-        if (this._isAutoBackgroundEnabled() && remotePlayer._isPlaying) {
+        if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning() && remotePlayer._isPlaying) {
             this._startCountdown();
         }
     }
@@ -388,7 +402,7 @@ class Lifecycle extends LifecycleInterface {
 
     set autoBackgroundOnUIDelay(delay) {
         this._autoBackgroundOnUIDelay = delay;
-        if (this._isAutoBackgroundEnabled() && !remotePlayer._isPlaying) {
+        if (this._isAutoBackgroundEnabled() && this._isForegroundOrTransitioning() && !remotePlayer._isPlaying) {
             this._startCountdown();
         }
     }
@@ -408,9 +422,24 @@ class Lifecycle extends LifecycleInterface {
         // Only start countdown if delay is positive
         if (timeoutDelay > 0) {
             sdkLogger.debug("Starting countdown timeout", timeoutDelay, isPlaying ? "(video)" : "(UI)");
-            this._countdown = setTimeout(() => {
+            this._countdown = setTimeout(async () => {
                 sdkLogger.debug("Countdown timeout reached, moving to background");
-                this.moveToBackground();
+
+                // Create the event with cancelable: true
+                const event = new Event("beforestatechange", { cancelable: true });
+                event.state = this.UiState.BACKGROUND;
+                // Use the event manager to dispatch the event and wait for all listeners
+                await this._eventManager.dispatch("beforestatechange", event);
+                // Check if any listener called preventDefault()
+                if (event.defaultPrevented) {
+                    sdkLogger.info("moveToBackground was prevented by a listener");
+                    // Restart the countdown since the move was cancelled
+                    if (this._isForegroundOrTransitioning()) {
+                        this._startCountdown();
+                    }
+                } else {
+                    this.moveToBackground();
+                }
             }, timeoutDelay * 1000);
         } else {
             sdkLogger.debug("Countdown not started - delay is negative or zero");
@@ -424,8 +453,8 @@ class Lifecycle extends LifecycleInterface {
         if (this._countdown) {
             sdkLogger.debug("Stopping countdown timer");
             clearTimeout(this._countdown);
+            this._countdown = null;
         }
-        this._countdown = null;
     }
 
     /**
@@ -459,7 +488,7 @@ class Lifecycle extends LifecycleInterface {
     moveToForeground() {
         if (window.cefQuery) {
             const inTransition = this._isInTransition();
-            if (inTransition || this._state === this.UiState.FOREGROUND || this._state === this.UiState.IN_TRANSITION_TO_FOREGROUND) {
+            if (inTransition || this._isForegroundOrTransitioning()) {
                 sdkLogger.warn(`lifecycle moveToForeground: No need to transition to foreground, state: ${this._state} transition: ${inTransition}`);
                 return Promise.resolve(false);
             }
@@ -771,23 +800,19 @@ class Lifecycle extends LifecycleInterface {
         return Promise.reject("disconnect is not supported if NOT running e2e");
     }
 
+
     addEventListener(type, listener, options) {
-        if (type === "userdisconnected") {
-            // Use the event manager for userdisconnected events
+        if (Lifecycle._waitForListenersEvents.includes(type)) {
             this._eventManager.addEventListener(type, listener);
         } else {
-            // For all other event types, use the parent class implementation
             super.addEventListener(type, listener, options);
         }
     }
 
-
     removeEventListener(type, listener, options) {
-        if (type === "userdisconnected") {
-            // Use the event manager for userdisconnected events
+        if (Lifecycle._waitForListenersEvents.includes(type)) {
             this._eventManager.removeEventListener(type, listener);
         } else {
-            // For all other event types, use the parent class implementation
             super.removeEventListener(type, listener, options);
         }
     }

package/src/interface/lifecycle.js

@@ -13,6 +13,23 @@ import {
  * });
  */
 
+/**
+ * @event Lifecycle#beforestatechange
+ * @description Fired before transitioning to a new state. This event is cancelable.<br>
+ * Currently only fired when transitioning to BACKGROUND state (e.g., from autoBackground feature).<br>
+ * The actual state transition will occur after all event listeners have completed processing.
+ * Can be used to prevent automatic transitions to background state when using autoBackground feature.
+ * @property {UiState} state - Indicates the target state the lifecycle is trying to transition to.
+ * @property {boolean} cancelable - true, indicating the event can be cancelled using preventDefault()
+ * @example
+ * lifecycle.addEventListener("beforestatechange", (e) => {
+ *     if (e.state === lifecycle.UiState.BACKGROUND && userIsInteracting) {
+ *         // Prevent transition to background
+ *         e.preventDefault();
+ *     }
+ * });
+ */
+
 /**
  * @event Lifecycle#userinactivity
  * @description Fired after the ui has been inactive (i.e. no key presses) for a configurable number of seconds.<br>
@@ -265,7 +282,7 @@ class Lifecycle extends EventTarget {
     /**
      * Add event listener for lifecycle events
      * @param {string} type - The event type to listen for
-     * @param {Function} listener - The callback function. Listeners for 'userdisconnected' events should return a promise to ensure the event is processed before the application exits.
+     * @param {Function} listener - The callback function. Listeners for 'userdisconnected' and 'beforestatechange' events should return a promise to ensure the event is processed before the application exits.
      * @param {Object} options - Event listener options
      */
     addEventListener(type, listener, options) {

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.4.4";
+export const version = "4.4.5";