trtc-electron-sdk 13.4.802-beta.4 → 13.5.802-beta.1

package/liteav/extensions/MediaMixingManager/MediaMixingManager.d.ts

@@ -146,6 +146,7 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     private serverStatus;
     private serverMode;
     private addMediaSourceTimers;
+    private screenCaptureRectRestartCounts;
     private webRenderer;
     private pixelFormat;
     private pixelLength;
@@ -541,6 +542,65 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
      */
     private _isSameCaptureParams;
     private _omitIsPaused;
+    /**
+     * @private
+     * Strip `captureRect` from a screen param so that the remaining object maps
+     * 1:1 onto the native `TRTCScreenCaptureProperty` structure.
+     *
+     * The capture region travels with the media source payload of
+     * add/updateMediaSource (and is consumed by the native `startScreenSource`),
+     * not through `setScreenCaptureProperty`. Keeping it out of the property
+     * object avoids both sending a field the native setter ignores and a false
+     * "changed" verdict from `_isSameCaptureParams`.
+     */
+    private _omitCaptureRect;
+    /**
+     * @private
+     * Whether the capture region actually changed between two screen params.
+     *
+     * An absent `captureRect` means "leave the current capture region alone", so
+     * it never counts as a change. This mirrors the cpp-side diff, which only
+     * restarts the capture when a region is explicitly provided AND differs from
+     * the one currently applied.
+     */
+    private _isScreenCaptureRectChanged;
+    private _screenCaptureRectRestartKey;
+    /**
+     * @private
+     * Record that one screen-capture restart has been requested for this source,
+     * so the resulting `onMediaSourceAdded` echo can be recognized and skipped.
+     */
+    private _markScreenCaptureRectRestart;
+    /**
+     * @private
+     * Consume one pending restart marker. Returns true when the incoming
+     * notification is an echo of a capture-region restart we triggered ourselves.
+     */
+    private _consumeScreenCaptureRectRestart;
+    /**
+     * @private
+     * Drop any pending restart markers for this source.
+     *
+     * Called whenever a source is added or removed: a marker only makes sense for
+     * the lifetime of one particular capture session. Should the native layer ever
+     * fail to echo a restart, a stale marker left behind would otherwise swallow
+     * the genuine insertion notification of a later re-add.
+     */
+    private _clearScreenCaptureRectRestart;
+    /**
+     * @private
+     * Validate and normalize `screen.captureRect` in place.
+     *
+     * A rect is accepted when it is either all-zero (meaning "capture the whole
+     * target", matching the native default) or a well-formed region with a
+     * positive width and height. Anything else is dropped with a warning so that
+     * a malformed value never reaches the native layer and never disturbs the
+     * currently applied capture region.
+     *
+     * Only applies to kScreen sources; `captureRect` on any other source type is
+     * meaningless and is removed as well.
+     */
+    private _normalizeScreenCaptureRect;
     private _setVideoFilePaused;
     private previewInNativeWindow;
     private previewInWebElement;

package/liteav/extensions/MediaMixingManager/MediaMixingManager.js

@@ -119,6 +119,33 @@ const TRTCOnlineVideoParam_HACK_JSDOC = null;
  * @property {Number} playoutVolume 播放音量，取值 0 - 100
  */
 const TRTCVideoFileParam_HACK_JSDOC = null;
+/**
+ * 本地视频文件媒体源参数
+ *
+ * 继承 `TRTCVideoFileParam` 的全部属性，并额外支持控制播放/暂停。
+ *
+ * @typedef {Object} TRTCMediaMixingLocalVideoParam
+ * @property {Number} playoutVolume 播放音量，取值 0 - 100
+ * @property {Boolean} isPaused 是否暂停播放，可选属性，默认 false（即播放）。
+ * `updateMediaSource` 时仅在该属性变化时才会下发暂停/恢复操作。
+ */
+const TRTCMediaMixingLocalVideoParam_HACK_JSDOC = null;
+/**
+ * 屏幕/窗口采集参数
+ *
+ * 继承 `TRTCScreenCaptureProperty` 的全部属性，并额外支持指定采集区域。
+ *
+ * @typedef {Object} TRTCMediaMixingScreenParam
+ * @property {Boolean} enableCaptureMouse 是否采集目标内容的同时采集鼠标，可选属性，默认 true
+ * @property {Boolean} enableHighLight 是否高亮正在共享的窗口，可选属性，默认 true
+ * @property {Boolean} enableHighPerformance 是否开启高性能模式（仅分享屏幕时生效），可选属性，默认 true
+ * @property {Number} highLightColor 高亮边框颜色，RGB 格式，可选属性，传 0 使用默认颜色
+ * @property {Number} highLightWidth 高亮边框宽度，可选属性，传 0 使用默认宽度
+ * @property {Boolean} enableCaptureChildWindow 窗口采集时是否采集子窗口，可选属性，默认 false
+ * @property {Rect} captureRect 采集区域，单位：像素，可选属性。不传或传入全零表示采集完整画面；
+ * 传入合法区域（`right > left` 且 `bottom > top`）表示仅采集指定区域，非法区域会被忽略。
+ */
+const TRTCMediaMixingScreenParam_HACK_JSDOC = null;
 /**
  * 媒体源数据
  *
@@ -129,12 +156,14 @@ const TRTCVideoFileParam_HACK_JSDOC = null;
  * @property {Boolean} enableGreenScreen 是否开启绿幕（仅在 sourceType 为 kCamera 时生效），可选属性
  * @property {Rect} rect 媒体源显示区域
  * @property {Boolean} isSelected 媒体源是否选中，可选属性，默认：false
- * @property {TRTCVideoRotation} rotation 媒体源选中角度，可选属性
+ * @property {Boolean} isLocked 媒体源是否锁定，可选属性，默认：false。锁定后该媒体源无法通过预览画布上的
+ * 点击、拖拽、缩放进行交互（即使被外部列表强制置为选中状态，也不会显示移动/缩放控件）。
+ * @property {TRTCVideoRotation} rotation 媒体源旋转角度，可选属性
  * @property {TRTCVideoFillMode} fillMode 媒体源显示模式，可选属性，默认 `TRTCVideoFillMode_Fit`
  * @property {TRTCVideoMirrorType} mirrorType 媒体源是否镜像，可选属性，默认不镜像
  * @property {TRTCCameraCaptureParams} camera 摄像头采集参数，仅在 sourceType 为 kCamera 时生效，可选属性
- * @property {TRTCScreenCaptureProperty} screen 屏幕/窗口采集属性，仅在 sourceType 为 kScreen 时生效，可选属性
- * @property {TRTCVideoFileParam} localVideo 本地视频文件播放参数，仅在 sourceType 为 kVideoFile 时生效，可选属性
+ * @property {TRTCMediaMixingScreenParam} screen 屏幕/窗口采集参数，仅在 sourceType 为 kScreen 时生效，可选属性
+ * @property {TRTCMediaMixingLocalVideoParam} localVideo 本地视频文件播放参数，仅在 sourceType 为 kVideoFile 时生效，可选属性
  * @property {TRTCOnlineVideoParam} onlineVideo 在线视频播放参数，仅在 sourceType 为 kOnlineVideo 时生效，可选属性
  */
 const TRTCMediaSource_HACK_JSDOC = null;
@@ -356,6 +385,17 @@ class TRTCMediaMixingManager {
         // state machine stuck after a previous failure), which would otherwise leave
         // the returned Promise pending forever and the UI stuck on "loading".
         this.addMediaSourceTimers = new Map();
+        // Number of screen-capture restarts we have deliberately triggered per
+        // source, keyed by `${sourceType}-${sourceId}`.
+        //
+        // Changing `screen.captureRect` can only take effect by re-invoking the
+        // native `startScreenSource`, which makes the underlying SDK emit another
+        // `onScreenSourceStarted` -> `SM_OnSourceInserted`. That notification is an
+        // echo of an already-added source, not a new insertion, so it must not be
+        // mistaken for one. We count the restarts we asked for and swallow exactly
+        // that many successful notifications. A counter (rather than a flag) keeps
+        // rapid successive updates correct, since every restart echoes back once.
+        this.screenCaptureRectRestartCounts = new Map();
         this.webRenderer = null;
         this.pixelFormat = trtc_define_1.TRTCVideoPixelFormat.TRTCVideoPixelFormat_BGRA32;
         this.pixelLength = 4;
@@ -443,6 +483,7 @@ class TRTCMediaMixingManager {
             // callbacks touching a destroyed instance.
             this.addMediaSourceTimers.forEach(timer => clearTimeout(timer));
             this.addMediaSourceTimers.clear();
+            this.screenCaptureRectRestartCounts.clear();
             this.paramsStore = null;
             this.trtcParamsStore = null;
             // 仅解除引用，pluginManager 生命周期由 TRTCCloud 统一管理
@@ -585,6 +626,7 @@ class TRTCMediaMixingManager {
                 });
             }
             const newMediaSource = (0, utils_1.safelyParse)(JSON.stringify(mediaSource));
+            this._normalizeScreenCaptureRect(newMediaSource);
             if (newMediaSource.isSelected) {
                 const oldSelectedIndex = this.findSelectedMediaSource();
                 if (oldSelectedIndex !== -1) {
@@ -651,6 +693,9 @@ class TRTCMediaMixingManager {
                 // extra camera restart on first add. Other source types are handled in
                 // the onMediaSourceAdded callback once the C++ layer reports success.
                 this._applyCameraParamsBeforeAdd(newMediaSource);
+                // A fresh capture session starts here, so no restart echo can still be
+                // outstanding from a previous one.
+                this._clearScreenCaptureRectRestart(newMediaSource.sourceType, newMediaSource.sourceId);
                 this.nodeMediaMixingPlugin.addMediaSource(newMediaSource);
                 (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.addMedia({
                     id: `${newMediaSource.sourceType}__${newMediaSource.sourceId}`,
@@ -717,6 +762,7 @@ class TRTCMediaMixingManager {
     }
     jsRemoveMediaSource(mediaSource, index) {
         var _a;
+        this._clearScreenCaptureRectRestart(mediaSource.sourceType, mediaSource.sourceId);
         (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.removeMedia({
             id: `${mediaSource.sourceType}__${mediaSource.sourceId}`,
             rect: mediaSource.rect,
@@ -733,7 +779,7 @@ class TRTCMediaMixingManager {
      * @returns {Promise<void>}
      */
     updateMediaSource(mediaSource) {
-        var _a;
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
             logger_1.default.log(`${this.logPrefix}updateMediaSource:`, mediaSource);
             const index = this.findMediaSourceIndex(mediaSource);
@@ -744,15 +790,36 @@ class TRTCMediaMixingManager {
                 });
             }
             const newMediaSource = Object.assign(Object.assign({}, this.sourceList[index]), (0, utils_1.safelyParse)(JSON.stringify(mediaSource)));
+            this._normalizeScreenCaptureRect(newMediaSource);
             if (mediaSource.isSelected) {
                 const oldSelectedIndex = this.findSelectedMediaSource();
                 if (oldSelectedIndex !== -1 && oldSelectedIndex !== index) {
                     yield this.unselectMediaSource(oldSelectedIndex);
                 }
             }
-            yield this.nodeMediaMixingPlugin.updateMediaSource(newMediaSource);
+            // The cpp layer re-invokes `startScreenSource` when the capture region
+            // changes, which echoes back one extra `SM_OnSourceInserted`. Record it
+            // before the call so the echo can be recognized instead of being handled
+            // as a brand-new insertion.
+            const captureRectChanged = newMediaSource.sourceType === types_1.TRTCMediaSourceType.kScreen
+                && this._isScreenCaptureRectChanged(newMediaSource.screen, (_a = this.sourceList[index]) === null || _a === void 0 ? void 0 : _a.screen);
+            if (captureRectChanged) {
+                this._markScreenCaptureRectRestart(newMediaSource.sourceType, newMediaSource.sourceId);
+            }
+            try {
+                yield this.nodeMediaMixingPlugin.updateMediaSource(newMediaSource);
+            }
+            catch (err) {
+                // The native call failed before the capture restart could happen, so
+                // the expected echo will never arrive. Roll the marker back, otherwise
+                // the stale one would swallow a genuine insertion notification later.
+                if (captureRectChanged) {
+                    this._clearScreenCaptureRectRestart(newMediaSource.sourceType, newMediaSource.sourceId);
+                }
+                throw err;
+            }
             this._applyMediaSourceParams(newMediaSource, this.sourceList[index]);
-            (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.updateMedia({
+            (_b = this.mediaMixingDesigner) === null || _b === void 0 ? void 0 : _b.updateMedia({
                 id: `${mediaSource.sourceType}__${mediaSource.sourceId}`,
                 rect: mediaSource.rect,
                 isSelected: mediaSource.isSelected || false,
@@ -1369,6 +1436,19 @@ class TRTCMediaMixingManager {
             clearTimeout(timer);
             this.addMediaSourceTimers.delete(promiseKey);
         }
+        // Deduplicate the echo of a capture-region restart that we triggered from
+        // updateMediaSource: the source is already tracked and its params are
+        // already applied, so re-running the add bookkeeping would only issue a
+        // redundant setScreenCaptureProperty. Failures are deliberately NOT
+        // swallowed - they still need to reach the caller through the normal
+        // error path below.
+        if (data.errCode === 0 && this._consumeScreenCaptureRectRestart(data.sourceType, data.sourceId)) {
+            logger_1.default.log(`${this.logPrefix}screen capture rect restarted for sourceId:${data.sourceId}, skip duplicated onMediaSourceAdded`);
+            return;
+        }
+        if (data.errCode !== 0) {
+            this._clearScreenCaptureRectRestart(data.sourceType, data.sourceId);
+        }
         let flag = false;
         if (data.errCode === 0) {
             const addedIndex = this.findMediaSourceIndex({
@@ -1567,6 +1647,11 @@ class TRTCMediaMixingManager {
                 if ((_b = this.paramsStore) === null || _b === void 0 ? void 0 : _b.streamLayout) {
                     this.setStreamLayout(this.paramsStore.streamLayout);
                 }
+                // The restarted media server holds no capture session yet, so every
+                // source below is a genuine insertion. Drop restart markers left over
+                // from before the crash, otherwise a stale one would swallow a recovery
+                // notification and skip re-applying that source's capture params.
+                this.screenCaptureRectRestartCounts.clear();
                 this.sourceList.forEach((item) => {
                     this._applyCameraParamsBeforeAdd(item);
                     this.nodeMediaMixingPlugin.addMediaSource(item);
@@ -1657,11 +1742,15 @@ class TRTCMediaMixingManager {
                     this.setCameraCaptureParam(mediaSource.sourceId, mediaSource.camera);
                 }
                 break;
-            case types_1.TRTCMediaSourceType.kScreen:
-                if (mediaSource.screen && !this._isSameCaptureParams(mediaSource.screen, oldMediaSource === null || oldMediaSource === void 0 ? void 0 : oldMediaSource.screen)) {
-                    this.setScreenCaptureProperty(mediaSource.sourceId, mediaSource.screen);
+            case types_1.TRTCMediaSourceType.kScreen: {
+                const nextProperty = this._omitCaptureRect(mediaSource.screen);
+                const prevProperty = this._omitCaptureRect(oldMediaSource === null || oldMediaSource === void 0 ? void 0 : oldMediaSource.screen);
+                if (nextProperty && Object.keys(nextProperty).length > 0
+                    && !this._isSameCaptureParams(nextProperty, prevProperty)) {
+                    this.setScreenCaptureProperty(mediaSource.sourceId, nextProperty);
                 }
                 break;
+            }
             case types_1.TRTCMediaSourceType.kOnlineVideo:
                 if (mediaSource.onlineVideo && !this._isSameCaptureParams(mediaSource.onlineVideo, oldMediaSource === null || oldMediaSource === void 0 ? void 0 : oldMediaSource.onlineVideo)) {
                     this.setOnlineVideoParam(mediaSource.sourceId, mediaSource.onlineVideo);
@@ -1724,6 +1813,122 @@ class TRTCMediaMixingManager {
         const { isPaused } = param, rest = __rest(param, ["isPaused"]);
         return rest;
     }
+    /**
+     * @private
+     * Strip `captureRect` from a screen param so that the remaining object maps
+     * 1:1 onto the native `TRTCScreenCaptureProperty` structure.
+     *
+     * The capture region travels with the media source payload of
+     * add/updateMediaSource (and is consumed by the native `startScreenSource`),
+     * not through `setScreenCaptureProperty`. Keeping it out of the property
+     * object avoids both sending a field the native setter ignores and a false
+     * "changed" verdict from `_isSameCaptureParams`.
+     */
+    _omitCaptureRect(param) {
+        if (!param) {
+            return undefined;
+        }
+        const { captureRect } = param, rest = __rest(param, ["captureRect"]);
+        return rest;
+    }
+    /**
+     * @private
+     * Whether the capture region actually changed between two screen params.
+     *
+     * An absent `captureRect` means "leave the current capture region alone", so
+     * it never counts as a change. This mirrors the cpp-side diff, which only
+     * restarts the capture when a region is explicitly provided AND differs from
+     * the one currently applied.
+     */
+    _isScreenCaptureRectChanged(next, prev) {
+        const nextRect = next === null || next === void 0 ? void 0 : next.captureRect;
+        if (nextRect === undefined || nextRect === null) {
+            return false;
+        }
+        return !(0, lodash_isequal_1.default)(nextRect, prev === null || prev === void 0 ? void 0 : prev.captureRect);
+    }
+    _screenCaptureRectRestartKey(sourceType, sourceId) {
+        return `${sourceType}-${sourceId}`;
+    }
+    /**
+     * @private
+     * Record that one screen-capture restart has been requested for this source,
+     * so the resulting `onMediaSourceAdded` echo can be recognized and skipped.
+     */
+    _markScreenCaptureRectRestart(sourceType, sourceId) {
+        const key = this._screenCaptureRectRestartKey(sourceType, sourceId);
+        this.screenCaptureRectRestartCounts.set(key, (this.screenCaptureRectRestartCounts.get(key) || 0) + 1);
+    }
+    /**
+     * @private
+     * Consume one pending restart marker. Returns true when the incoming
+     * notification is an echo of a capture-region restart we triggered ourselves.
+     */
+    _consumeScreenCaptureRectRestart(sourceType, sourceId) {
+        const key = this._screenCaptureRectRestartKey(sourceType, sourceId);
+        const count = this.screenCaptureRectRestartCounts.get(key) || 0;
+        if (count <= 0) {
+            return false;
+        }
+        if (count === 1) {
+            this.screenCaptureRectRestartCounts.delete(key);
+        }
+        else {
+            this.screenCaptureRectRestartCounts.set(key, count - 1);
+        }
+        return true;
+    }
+    /**
+     * @private
+     * Drop any pending restart markers for this source.
+     *
+     * Called whenever a source is added or removed: a marker only makes sense for
+     * the lifetime of one particular capture session. Should the native layer ever
+     * fail to echo a restart, a stale marker left behind would otherwise swallow
+     * the genuine insertion notification of a later re-add.
+     */
+    _clearScreenCaptureRectRestart(sourceType, sourceId) {
+        this.screenCaptureRectRestartCounts.delete(this._screenCaptureRectRestartKey(sourceType, sourceId));
+    }
+    /**
+     * @private
+     * Validate and normalize `screen.captureRect` in place.
+     *
+     * A rect is accepted when it is either all-zero (meaning "capture the whole
+     * target", matching the native default) or a well-formed region with a
+     * positive width and height. Anything else is dropped with a warning so that
+     * a malformed value never reaches the native layer and never disturbs the
+     * currently applied capture region.
+     *
+     * Only applies to kScreen sources; `captureRect` on any other source type is
+     * meaningless and is removed as well.
+     */
+    _normalizeScreenCaptureRect(mediaSource) {
+        const screen = mediaSource.screen;
+        if (!screen || screen.captureRect === undefined || screen.captureRect === null) {
+            return;
+        }
+        if (mediaSource.sourceType !== types_1.TRTCMediaSourceType.kScreen) {
+            logger_1.default.warn(`${this.logPrefix}screen.captureRect is only supported for kScreen source, ignored. sourceType:${mediaSource.sourceType}`);
+            delete screen.captureRect;
+            return;
+        }
+        const { left, top, right, bottom } = screen.captureRect;
+        const isValidNumber = [left, top, right, bottom].every(item => typeof item === 'number' && Number.isInteger(item) && item >= -2147483648 && item <= 2147483647);
+        if (!isValidNumber) {
+            logger_1.default.warn(`${this.logPrefix}screen.captureRect must contain int32 integers, ignored:`, screen.captureRect);
+            delete screen.captureRect;
+            return;
+        }
+        const isFullTarget = left === 0 && top === 0 && right === 0 && bottom === 0;
+        if (isFullTarget) {
+            return;
+        }
+        if (left < 0 || top < 0 || right <= left || bottom <= top) {
+            logger_1.default.warn(`${this.logPrefix}screen.captureRect is invalid, ignored:`, screen.captureRect);
+            delete screen.captureRect;
+        }
+    }
     _setVideoFilePaused(sourceId, isPaused) {
         if (isPaused) {
             this.nodeMediaMixingPlugin.pauseVideoFileSource(sourceId);

package/liteav/extensions/MediaMixingManager/types.d.ts

@@ -49,6 +49,9 @@ export declare type TRTCVideoFileParam = {
 export declare type TRTCMediaMixingLocalVideoParam = TRTCVideoFileParam & {
     isPaused?: boolean;
 };
+export declare type TRTCMediaMixingScreenParam = TRTCScreenCaptureProperty & {
+    captureRect?: Rect;
+};
 export declare type TRTCMediaSource = {
     sourceType: TRTCMediaSourceType;
     sourceId: string;
@@ -61,7 +64,7 @@ export declare type TRTCMediaSource = {
     fillMode?: TRTCVideoFillMode;
     mirrorType?: TRTCVideoMirrorType;
     camera?: TRTCCameraCaptureParams;
-    screen?: TRTCScreenCaptureProperty;
+    screen?: TRTCMediaMixingScreenParam;
     localVideo?: TRTCMediaMixingLocalVideoParam;
     onlineVideo?: TRTCOnlineVideoParam;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trtc-electron-sdk",
-  "version": "13.4.802-beta.4",
+  "version": "13.5.802-beta.1",
   "description": "trtc electron sdk",
   "main": "./liteav/index.js",
   "types": "./liteav/index.d.ts",