senza-sdk 4.5.8 → 4.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "senza-sdk",
-    "version": "4.5.8",
+    "version": "4.5.9",
     "main": "./src/api.js",
     "description": "API for Senza application",
     "license": "MIT",
@@ -18,6 +18,8 @@
         "build:interface": "npx webpack --config interface.webpack.config.js",
         "prebuild:implementation": "npm run version:output",
         "build:implementation": "npx webpack --config implementation.webpack.config.js",
+        "build:dual-decode-sample": "npm run build && mkdir -p samples/dualDecode/sdk && cp dist/bundle.js dist/implementation.bundle.js samples/dualDecode/sdk/ && npm run build:dual-decode-sample:app",
+        "build:dual-decode-sample:app": "npx webpack --config samples/dualDecode/webpack.config.js --context samples/dualDecode",
         "test": "jest --maxWorkers=20% --coverage --verbose",
         "testall": "npm run test && npm run eslint --fix",
         "version:output": "echo 'export const version = \"'$npm_package_version'\";' > src/interface/version.js"

package/src/implementation/lifecycle.js

@@ -27,6 +27,12 @@ const DEFAULT_AUTO_SUSPEND_IDLE_DELAY = 60;
 // Session storage key for tracking timer-triggered background state
 const BACKGROUND_TIMER_KEY = "senzaSDK_backgroundTriggeredByTimer";
 
+/** @enum {string} */
+const UiTransition = Object.freeze({
+    START_UI: "startUi",
+    STOP_UI: "stopUi"
+});
+
 class Lifecycle extends LifecycleInterface {
     constructor() {
         super();
@@ -552,6 +558,58 @@ class Lifecycle extends LifecycleInterface {
         return Promise.resolve(true);
     }
 
+    /**
+     * @private Sends a simple message to the client and resolves/rejects based on the response.
+     * Used by the dual decode startUi/stopUi transitions.
+     * @param {UiTransition} type the message type to send
+     * @returns {Promise<boolean>}
+     */
+    _sendUiTransition(type) {
+        if (window.cefQuery) {
+            return new Promise((resolve, reject) => {
+                const FCID = getFCID();
+                const logger = sdkLogger.withFields({ FCID });
+                const message = { type, fcid: FCID };
+                // Mirror V2 remotePlayer lifecycle: ui-streamer resumes/pauses locally via internalAction
+                // while TC receives startUi/stopUi on the datachannel.
+                const internalAction = type === UiTransition.START_UI ? "uiActive" : "uiExit";
+                // TC confirms stopUi with isResponse; startUi is fire-and-forget until TC adds a response.
+                const waitForResponse = type !== UiTransition.START_UI;
+                const request = { target: "TC", waitForResponse, internalAction, message: JSON.stringify(message) };
+                window.cefQuery({
+                    request: JSON.stringify(request),
+                    persistent: false,
+                    onSuccess: () => {
+                        logger.log(`${type} successfully sent`);
+                        resolve(true);
+                    },
+                    onFailure: (code, msg) => {
+                        logger.error(`${type} failed: ${code} ${msg}`);
+                        reject(new SenzaError(code, msg));
+                    }
+                });
+            });
+        }
+        sdkLogger.warn(`lifecycle ${type}: window.cefQuery is undefined`);
+        return Promise.resolve(true);
+    }
+
+    /**
+     * @private Starts the UI streaming.
+     * @returns {Promise<boolean>}
+     */
+    _startUi() {
+        return this._sendUiTransition(UiTransition.START_UI);
+    }
+
+    /**
+     * @private Stops the UI streaming.
+     * @returns {Promise<boolean>}
+     */
+    _stopUi() {
+        return this._sendUiTransition(UiTransition.STOP_UI);
+    }
+
     get state() {
         if (!this._isInitialized) {
             this._state = this.UiState.UNKNOWN;
@@ -725,6 +783,11 @@ class Lifecycle extends LifecycleInterface {
         this._isBackgroundTriggeredByTimer = false;
 
         if (window.cefQuery) {
+            if (remotePlayer._isDualDecodeActive()) {
+                // Cancel a pending dual-decode background transition that is waiting for the playing event.
+                this._inTransitionToBackground = false;
+            }
+
             const inTransition = this._isInTransition();
             if (inTransition || this._isForegroundOrTransitioning()) {
                 sdkLogger.warn(`lifecycle moveToForeground: No need to transition to foreground, state: ${this._state} transition: ${inTransition}`);
@@ -746,11 +809,23 @@ class Lifecycle extends LifecycleInterface {
             this._inTransitionToForeground = true;
             bus.dispatchEvent(new Event(Events.LifecycleForeground));
             const FCID = getFCID();
+
             if (this._remotePlayerApiVersion >= 2) {
                 // Only update to playing UI if we started seeking in ABR. But, if we are seeking while already paused, keep the target seek state as is.
                 if (remotePlayer._isSeekingByApplication && remotePlayer._targetSeekPlayingState === TargetPlayingState.PLAYING_ABR) {
                     remotePlayer._targetSeekPlayingState = TargetPlayingState.PLAYING_UI;
                 }
+
+                if (remotePlayer._isDualDecodeActive()) {
+                    // In dual decode mode, returning to the UI only requires (re)showing the UI on top of the ABR video.
+                    // We must not stop the remote player playback, so skip the v2 uiActive/stop and legacy uiActiveRequest paths.
+                    try {
+                        return await this._startUi();
+                    } finally {
+                        this._inTransitionToForeground = false;
+                    }
+                }
+
                 return new Promise((resolve, reject) => {
                     const FCID = getFCID();
                     const logger = sdkLogger.withFields({ FCID });
@@ -817,6 +892,31 @@ class Lifecycle extends LifecycleInterface {
         return Promise.resolve(false);
     }
 
+    /**
+     * @private Handles the dual decode background transition: hide the UI via stopUi.
+     * Does not send any play/uiExit message. If the remote "playing" event has not arrived yet,
+     * stopUi is still called immediately and a warning is logged.
+     *
+     * @returns {Promise<boolean>} stopUi result
+     */
+    _moveToBackgroundDualDecode() {
+        if (remotePlayer._isPlayingEventPending) {
+            sdkLogger.warn("dual decode moveToBackground: moving to background before the playing event arrived; stopping the UI now");
+        } else {
+            sdkLogger.info("dual decode moveToBackground: playing event already arrived, stopping the UI");
+        }
+        this._inTransitionToBackground = true;
+        return this._stopUi()
+            .then((result) => {
+                this._inTransitionToBackground = false;
+                return result;
+            })
+            .catch((error) => {
+                this._inTransitionToBackground = false;
+                throw error;
+            });
+    }
+
     _moveToBackground(switchMode = SwitchMode.SEAMLESS) {
         /*const inTransition = this._isInTransition();
         if (inTransition || this._state === this.UiState.BACKGROUND || this._state === this.UiState.IN_TRANSITION_TO_BACKGROUND) {
@@ -846,6 +946,11 @@ class Lifecycle extends LifecycleInterface {
                 return this._moveToUiStandby();
             }
             remotePlayer._changePlayMode(true);
+
+            if (remotePlayer._isDualDecodeActive()) {
+                return this._moveToBackgroundDualDecode();
+            }
+
             this._inTransitionToBackground = true;
             return new Promise((resolve, reject) => {
                 const FCID = getFCID();

package/src/implementation/remotePlayer.js

@@ -4,10 +4,13 @@ import {
     getFCID,
     generatePlaybackId,
     isAudioSyncConfigured,
+    isDualDecodeEnabled,
+    getDualDecodeAbrSurfaceSize,
     clearTimer,
     sdkLogger,
     StreamType,
     SwitchMode,
+    VideoLayer,
     delay,
     SeekState,
     TargetPlayingState,
@@ -68,6 +71,8 @@ function setPlaybackInfo(playbackInfo) {
 }
 
 class RemotePlayer extends RemotePlayerInterface {
+    VideoLayer = VideoLayer;
+
     constructor() {
         super();
         /**
@@ -154,6 +159,13 @@ class RemotePlayer extends RemotePlayerInterface {
          */
         this._playbackId = "";
 
+        /**
+         * @type {boolean}
+         * @description True while a dual-decode play() is awaiting the remote "playing" event.
+         * @private
+         */
+        this._isPlayingEventPending = false;
+
         /**
          * Anchor position in seconds used by getPlaybackPosition().
          * @type {number}
@@ -270,6 +282,9 @@ class RemotePlayer extends RemotePlayerInterface {
         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));
+            if (e?.detail?.eventName === "playing") {
+                this._isPlayingEventPending = false;
+            }
             this.dispatchEvent(new Event(e?.detail?.eventName));
         });
 
@@ -585,6 +600,7 @@ class RemotePlayer extends RemotePlayerInterface {
         this._availabilityStartTime = undefined;
         this._isSeekingByPlatform = false;
         this._isSeekingByApplication = false;
+        this._isPlayingEventPending = false;
         this._stopPlaybackClock();
         this._playbackPositionAnchor = 0;
     }
@@ -685,6 +701,12 @@ class RemotePlayer extends RemotePlayerInterface {
             } else if (!this.textTrackVisibility) {
                 message.subtitlesLanguage = "";
             }
+            if (switchMode === SwitchMode.DUAL_DECODE) {
+                message.switchMode = SwitchMode.DUAL_DECODE;
+                message.streamType = streamType;
+                waitForResponse = true;
+                this._isPlayingEventPending = true;
+            }
             logger.log(`remotePlayer play: sending play action remotePlayer._isPlaying: ${this._isPlaying} audioLanguage=${message.audioLanguage} subtitlesLanguage=${message.subtitlesLanguage} textTrackVisibility=${this.textTrackVisibility}`);
             const request = { target: "TC", waitForResponse: waitForResponse, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
@@ -703,6 +725,7 @@ class RemotePlayer extends RemotePlayerInterface {
                         const duration = Date.now() - timeBeforeSendingRequest;
                         logger.withFields({ duration }).log(`play failed after ${duration} ms. Error code: ${code}, error message: ${msg}`);
                         timerId = clearTimer(timerId);
+                        this._isPlayingEventPending = false;
                         reject(new RemotePlayerError(code, msg));
                     }
                 });
@@ -727,7 +750,7 @@ class RemotePlayer extends RemotePlayerInterface {
 
         if (window.cefQuery) {
             const isForegroundState = lifecycle.state === lifecycle.UiState.FOREGROUND || lifecycle.state === lifecycle.UiState.IN_TRANSITION_TO_FOREGROUND;
-            if (this._remotePlayerApiVersion >= 2 && !this._isAudioSyncEnabled() && isForegroundState) {
+            if (this._remotePlayerApiVersion >= 2 && !this._isAudioSyncEnabled() && !this._isDualDecodeActive() && isForegroundState) {
                 sdkLogger.info("remotePlayer pause: application in foreground, remote player is not playing.");
                 return Promise.resolve();
             }
@@ -793,6 +816,12 @@ class RemotePlayer extends RemotePlayerInterface {
                 fcid: FCID,
                 playbackId: this._playbackId
             };
+            if (this._isDualDecodeActive()) {
+                message.switchMode = SwitchMode.DUAL_DECODE;
+                if (streamType & StreamType.VIDEO) {
+                    this._isPlayingEventPending = false;
+                }
+            }
             const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
             return new Promise((resolve, reject) => {
                 let timerId = 0;
@@ -1026,6 +1055,7 @@ class RemotePlayer extends RemotePlayerInterface {
             this._abortSetAudioLanguage = true;
             this._abortSetSubtitleLanguage = true;
             this._abortSeeking = true;
+            this._isPlayingEventPending = false;
             const previousLoadMode = this._loadMode;
             this._changeLoadMode(this.LoadMode.UNLOADING);
             this._changePlayMode(false);
@@ -1113,6 +1143,17 @@ class RemotePlayer extends RemotePlayerInterface {
         this._changePlayMode(true);
         this._autoTune = autoTune;
 
+        if (this._isDualDecodeActive()) {
+            // In dual decode mode, ABR video is rendered over the UI video, so we always play audio + video
+            // (and subtitles when visible) using the DUAL_DECODE switch mode, bypassing the foreground/audio-sync
+            // early returns below. Start the waitForPlaying timer so callers (e.g. moveToBackground)
+            // can wait for the remote player to actually start playing.
+            const dualDecodeStreamType = this.textTrackVisibility
+                ? (StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE)
+                : (StreamType.AUDIO | StreamType.VIDEO);
+            return this._play(dualDecodeStreamType, SwitchMode.DUAL_DECODE);
+        }
+
         if (this._isSetAudioInProgress) {
             sdkLogger.info("application requesting play during setAudioLanguage");
             this._targetSetAudioPlayingState = TargetPlayingState.PLAYING_UI;
@@ -1198,6 +1239,18 @@ class RemotePlayer extends RemotePlayerInterface {
         return this._pause();
     }
 
+    /** Stop playback of all streams (audio, video and subtitles).
+     * @returns {Promise}
+     * @throws {RemotePlayerError} error object contains code & msg
+     *
+     * */
+    stop() {
+        if (!this._isInitialized) {
+            throw new RemotePlayerError(6500, "Cannot call stop() if remote player is not initialized");
+        }
+        return this._stop(StreamType.AUDIO | StreamType.VIDEO | StreamType.SUBTITLE);
+    }
+
     /** Get the currently loaded uri, or empty string is player is not loaded.
      * @returns {string} loaded uri
      * @throws {RemotePlayerError} error object contains code & msg
@@ -1654,6 +1707,109 @@ class RemotePlayer extends RemotePlayerInterface {
         return this._setScreenBlackout(0);
     }
 
+    /**
+     * @private
+     * Whether dual decode is active for this player (remote player API v2+ and session capability/settings enabled).
+     * @returns {boolean}
+     */
+    _isDualDecodeActive() {
+        return this._remotePlayerApiVersion >= 2 && isDualDecodeEnabled();
+    }
+
+    /** Set the position and size of the remote player (ABR) video on screen, or make it fullscreen.
+     * Only available when dual decode is enabled.
+     * The given rectangle is expressed in the UI coordinate space (window.innerWidth/window.innerHeight)
+     * and is validated and scaled to the client's ABR surface size before being sent to the client.
+     * @param {Object} rect
+     * @param {number} [rect.x] horizontal position in px (UI coordinate space)
+     * @param {number} [rect.y] vertical position in px (UI coordinate space)
+     * @param {number} [rect.width] width in px (UI coordinate space)
+     * @param {number} [rect.height] height in px (UI coordinate space)
+     * @param {boolean} [rect.fullScreen=false] when true, the video is rendered fullscreen and the rect is ignored
+     * @param {VideoLayer} [rect.layer=VideoLayer.FRONT] which layer the ABR video should be rendered on
+     * @returns {Promise}
+     * @throws {RemotePlayerError} error object contains code & msg
+     */
+    setVideoRect({ x, y, width, height, fullScreen = false, layer } = {}) {
+        if (!this._isDualDecodeActive()) {
+            throw new RemotePlayerError(6506, "Cannot call setVideoRect() when dual decode is not enabled");
+        }
+
+        layer = layer ?? VideoLayer.FRONT;
+
+        const FCID = getFCID();
+        const message = {
+            type: "remotePlayer.setVideoRect",
+            class: "remotePlayer",
+            action: "setVideoRect",
+            fcid: FCID,
+            playbackId: this._playbackId,
+            layer
+        };
+
+        if (fullScreen) {
+            message.fullScreen = true;
+        } else {
+            const winW = window.innerWidth;
+            const winH = window.innerHeight;
+            const isValid = [x, y, width, height].every((value) => typeof value === "number" && Number.isFinite(value) && value >= 0)
+                && x + width <= winW && y + height <= winH;
+            if (!isValid) {
+                throw new RemotePlayerError(6505, `setVideoRect() received invalid rectangle {x:${x}, y:${y}, width:${width}, height:${height}} for window {width:${winW}, height:${winH}}`);
+            }
+            const { width: abrW, height: abrH } = getDualDecodeAbrSurfaceSize();
+            message.x = Math.round(x * abrW / winW);
+            message.y = Math.round(y * abrH / winH);
+            message.width = Math.round(width * abrW / winW);
+            message.height = Math.round(height * abrH / winH);
+        }
+
+        if (window.cefQuery) {
+            const logger = sdkLogger.withFields({ FCID });
+            logger.log(`remotePlayer setVideoRect: sending setVideoRect action fullScreen=${!!fullScreen} layer=${layer}`);
+            const request = { target: "TC", waitForResponse: true, message: JSON.stringify(message) };
+            return new Promise((resolve, reject) => {
+                let timerId = 0;
+                const timeBeforeSendingRequest = Date.now();
+                const queryId = window.cefQuery({
+                    request: JSON.stringify(request),
+                    persistent: false,
+                    onSuccess: () => {
+                        const duration = Date.now() - timeBeforeSendingRequest;
+                        logger.withFields({ duration }).log(`setVideoRect completed successfully after ${duration} ms`);
+                        timerId = clearTimer(timerId);
+                        resolve();
+                    },
+                    onFailure: (code, msg) => {
+                        const duration = Date.now() - timeBeforeSendingRequest;
+                        logger.withFields({ duration }).log(`setVideoRect failed after ${duration} ms. Error code: ${code}, error message: ${msg}`);
+                        timerId = clearTimer(timerId);
+                        reject(new RemotePlayerError(code, msg));
+                    }
+                });
+                logger.log(`window.cefQuery for setVideoRect returned query id ${queryId}`);
+                const timeout = this._remotePlayerConfirmationTimeout + 1000;
+                timerId = setTimeout(() => {
+                    logger.log(`setVideoRect reached timeout of ${timeout} ms, canceling query id ${queryId}`);
+                    window.cefQueryCancel(queryId);
+                    reject(new RemotePlayerError(6000, `setVideoRect reached timeout of ${timeout} ms`));
+                }, timeout, queryId);
+            });
+        }
+        sdkLogger.error("remotePlayer setVideoRect: window.cefQuery is undefined");
+        return Promise.resolve(undefined);
+    }
+
+    /** Make the remote player (ABR) video fullscreen on the given layer.
+     * Only available when dual decode is enabled.
+     * @param {VideoLayer} [layer=VideoLayer.FRONT] which layer the ABR video should be rendered on
+     * @returns {Promise}
+     * @throws {RemotePlayerError} error object contains code & msg
+     */
+    setVideoFullscreen(layer) {
+        return this.setVideoRect({ fullScreen: true, layer: layer ?? VideoLayer.FRONT });
+    }
+
     /**
      * Getter/Setter for currentTime
      */

package/src/implementation/utils.js

@@ -140,6 +140,26 @@ export function isAudioSyncConfigured() {
     return clientUiAudioSettings?.enabled && clientUiAudioSettings?.from_cdn && clientUiAudioSettings?.ui_sync_enabled;
 }
 
+/** Dual decode is enabled only when both the client capability and the common settings report it as enabled.
+ * @returns {boolean}
+ */
+export function isDualDecodeEnabled() {
+    const sessionInfoObj = sessionInfo.sessionInfoObj;
+    return !!(sessionInfoObj?.capabilities?.dualDecode?.enabled && sessionInfoObj?.settings?.common?.dualDecode?.enabled);
+}
+
+/** Get the ABR surface size that dual decode video should be scaled to before being sent to the client.
+ * The values are read from the client capabilities and coerced to numbers (the platform may report them as strings).
+ * @returns {{width: number, height: number}}
+ */
+export function getDualDecodeAbrSurfaceSize() {
+    const abrSurfaceSize = sessionInfo.sessionInfoObj?.capabilities?.dualDecode?.abrSurfaceSize;
+    return {
+        width: Number(abrSurfaceSize?.width ?? 1280),
+        height: Number(abrSurfaceSize?.height ?? 720)
+    };
+}
+
 export function isSubtitlesTranslationAllowed() {
     return sessionInfo.sessionInfoObj?.settings?.["ui-streamer"]?.allowSubtitlesTranslation === true;
 }
@@ -181,7 +201,14 @@ export const StreamType = Object.freeze({
 
 export const SwitchMode = Object.freeze({
     NON_SEAMLESS: 0,
-    SEAMLESS: 1
+    SEAMLESS: 1,
+    DUAL_DECODE: 2
+});
+
+/** Layer on which dual-decode ABR video is composited (remotePlayer.setVideoRect). */
+export const VideoLayer = Object.freeze({
+    FRONT: 0,
+    BACK: 1
 });
 
 export const SeekState = Object.freeze({

package/src/interface/remotePlayer.js

@@ -132,6 +132,8 @@ export class RemotePlayerError extends Error {
  * | 6502      | Player            | unload() was called while previous unload/load was still in progress                            |
  * | 6503      | Player            | The remote player api call has invalid parameters                                               |
  * | 6504      | Player            | The remote player api internal error                                                            |
+ * | 6505      | Player            | setVideoRect() was called with an invalid rectangle (out of the window bounds or negative)      |
+ * | 6506      | Player            | setVideoRect() or setVideoFullscreen() was called when dual decode is not enabled               |
  * | 8001      | Player            | Error pulling manifest. bad parameters                                                          |
  * | 8002      | Player            | Error pulling manifest. filters returned no data                                                |
  * | 8003      | Player            | Error pulling manifest. fetch error                                                             |
@@ -246,6 +248,19 @@ class RemotePlayer extends EventTarget {
         SPOKEN_SUBTITLES: "9"
     };
 
+    /**
+     * @typedef {Object} VideoLayer
+     * @property {number} FRONT - The ABR video is rendered in front of the UI video.
+     * @property {number} BACK - The ABR video is rendered behind the UI video.
+     */
+    /** The layer on which the remote player (ABR) video is rendered when dual decode is enabled.
+     * @type {VideoLayer}
+     */
+    VideoLayer = Object.freeze({
+        FRONT: 0,
+        BACK: 1
+    });
+
     /** get the player configuration.
      * @returns {Config}
      * */
@@ -325,7 +340,7 @@ class RemotePlayer extends EventTarget {
         return noop("RemotePlayer.pause");
     }
 
-    /** Stop playback
+    /** Stop playback of all streams (audio, video and subtitles).
      * @returns {Promise}
      * @throws {RemotePlayerError} error object contains code & msg
      * */
@@ -333,6 +348,34 @@ class RemotePlayer extends EventTarget {
         return noop("RemotePlayer.stop");
     }
 
+    /** Set the position and size of the remote player (ABR) video on screen, or make it fullscreen.
+     * Only available when dual decode is enabled, otherwise throws.
+     * The given rectangle is expressed in the UI coordinate space (window.innerWidth/window.innerHeight)
+     * and is validated and scaled to the client's ABR surface size before being sent to the client.
+     * @param {Object} rect
+     * @param {number} [rect.x] horizontal position in px (UI coordinate space)
+     * @param {number} [rect.y] vertical position in px (UI coordinate space)
+     * @param {number} [rect.width] width in px (UI coordinate space)
+     * @param {number} [rect.height] height in px (UI coordinate space)
+     * @param {boolean} [rect.fullScreen=false] when true, the video is rendered fullscreen and the rect is ignored
+     * @param {VideoLayer} [rect.layer=VideoLayer.FRONT] which layer the ABR video should be rendered on
+     * @returns {Promise}
+     * @throws {RemotePlayerError} error object contains code & msg
+     */
+    setVideoRect(rect) {
+        return noop("RemotePlayer.setVideoRect", rect);
+    }
+
+    /** Make the remote player (ABR) video fullscreen on the given layer.
+     * Only available when dual decode is enabled, otherwise throws.
+     * @param {VideoLayer} [layer=VideoLayer.FRONT] which layer the ABR video should be rendered on
+     * @returns {Promise}
+     * @throws {RemotePlayerError} error object contains code & msg
+     */
+    setVideoFullscreen(layer = this.VideoLayer.FRONT) {
+        return noop("RemotePlayer.setVideoFullscreen", layer);
+    }
+
     /** Get the currently loaded uri, or empty string is player is not loaded.
      * @returns {string} loaded uri
      * @throws {RemotePlayerError} error object contains code & msg

package/src/interface/version.js

@@ -1 +1 @@
-export const version = "4.5.8";
+export const version = "4.5.9";