trtc-electron-sdk 13.4.801-alpha.0 → 13.4.802-beta.1

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

@@ -1,4 +1,5 @@
 import { TRTCCameraCaptureParams, Rect, TRTCScreenCaptureProperty } from '../../trtc_define';
+import TRTCPluginManager from '../PluginManager';
 import { TRTCMediaSource, TRTCMediaMixingEncParam, ITRTCMediaMixingManager, TRTCPhoneMirrorParam, TRTCStreamLayout, TRTCOnlineVideoParam, TRTCVideoFileParam } from './types';
 import { TRTCDeviceManager } from '../DeviceManager';
 declare const NodeTRTCEngine: any;
@@ -54,6 +55,8 @@ export declare enum TRTCMediaMixingEvent {
     onError = "onError",
     /**
      * @description 设备插入事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourcePlugged
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -62,6 +65,8 @@ export declare enum TRTCMediaMixingEvent {
     onSourcePlugged = "onSourcePlugged",
     /**
      * @description 设备链接事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceConnected
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -70,6 +75,8 @@ export declare enum TRTCMediaMixingEvent {
     onSourceConnected = "onSourceConnected",
     /**
      * @description 设备断开链接事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceDisconnected
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -78,6 +85,8 @@ export declare enum TRTCMediaMixingEvent {
     onSourceDisconnected = "onSourceDisconnected",
     /**
      * @description 设备拔出事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceUnplugged
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -95,6 +104,13 @@ export declare enum TRTCMediaMixingEvent {
      * @param {Number} size.height 媒体源最新高度
      */
     onMediaSourceSizeChanged = "onMediaSourceSizeChanged",
+    /**
+     * @description 本地混流服务丢失事件
+     * @deprecated
+     * @private
+     *
+     * @event TRTCMediaMixingEvent#onMediaMixingServerLost
+     */
     onMediaMixingServerLost = "onMediaMixingServerLost"
 }
 declare enum TRTCMediaMixingServerMode {
@@ -125,6 +141,7 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     private streamLayoutManager;
     private trtcParamsStore;
     private paramsStore;
+    private pluginManager;
     private autoControlServer;
     private serverStatus;
     private serverMode;
@@ -139,6 +156,7 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
         nodeTRTCCloud: typeof NodeTRTCEngine.NodeRemoteTRTCCloud;
         trtcParamsStore: Record<string, any>;
         autoControlServer: boolean;
+        pluginManager: TRTCPluginManager;
     });
     destroy(): Promise<void>;
     /**
@@ -241,13 +259,6 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
      * @returns {Promise<void>}
      */
     addMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
-    /**
-     * Returns the per-sourceType timeout (ms) used by addMediaSource. The
-     * defaults are intentionally larger than the cpp-layer timeout in
-     * SourceManagerProxy so that, in the normal case, the cpp side resolves the
-     * promise first. This JS timer is the last-resort safety net in case the
-     * cpp side itself fails to emit any callback (older builds, ipc lost, etc.).
-     */
     private getAddMediaSourceTimeoutMs;
     /**
      * 删除本地混流媒体源
@@ -265,12 +276,17 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     updateMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
     /**
      * 设置摄像头采集参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param cameraID {string} - 摄像头 ID
      * @param params {TRTCCameraCaptureParams} - 摄像头采集参数
      */
     setCameraCaptureParam(cameraID: string, params: TRTCCameraCaptureParams): void;
     /**
      * 设置手机投屏参数
+     *
+     * @deprecated
      * @private
      * @param phoneMirrorSourceId {string} - 手机投屏媒体源 ID
      * @param param {TRTCPhoneMirrorParam} - 手机投屏参数
@@ -278,18 +294,27 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     setPhoneMirrorParam(phoneMirrorSourceId: string, param: TRTCPhoneMirrorParam): void;
     /**
      * 设置屏幕采集参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param screenOrWindowID {String} - 屏幕 ID 或 窗口 ID
      * @param property {TRTCScreenCaptureProperty} - 屏幕采集属性
      */
     setScreenCaptureProperty(screenOrWindowID: string, property: TRTCScreenCaptureProperty): void;
     /**
      * 设置在线视频源播放参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param url {string} - 在线视频源 URL
      * @param param {TRTCOnlineVideoParam} - 在线视频源播放参数
      */
     setOnlineVideoParam(url: string, param: TRTCOnlineVideoParam): void;
     /**
      * 设置视频文件播放参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param videoFilePath {string} - 视频文件路径
      * @param param {TRTCVideoFileParam} - 视频文件播放参数
      */
@@ -458,9 +483,109 @@ export declare class TRTCMediaMixingManager implements ITRTCMediaMixingManager {
     private onCallExperimentalAPIFinish;
     private recoverMediaMixingServer;
     private onDevicePixelRatioChange;
+    /**
+     * @private
+     * Apply camera capture params BEFORE native addMediaSource.
+     *
+     * Calling setCameraCaptureParam after the camera has already been added
+     * triggers an extra camera restart (the camera first starts with default
+     * params and then restarts with the new ones). To avoid this we set
+     * camera params up-front for the add path. For all other source types
+     * the corresponding setters are dispatched in the post-add callback
+     * (`onMediaSourceAdded` -> `_applyMediaSourceParams`).
+     */
+    private _applyCameraParamsBeforeAdd;
+    /**
+     * @private
+     * Apply capture params from TRTCMediaSource to the native plugin.
+     *
+     * This method is called after media source is added or updated. To avoid
+     * costly side-effects of native setters (e.g. setCameraCaptureParam will
+     * restart the camera), the setter is invoked only when params are actually
+     * provided AND differ from the previous value carried by `oldMediaSource`.
+     *
+     * Camera handling differs by phase:
+     *   - Add path (oldMediaSource is undefined): camera params have been set
+     *     before native addMediaSource via `_applyCameraParamsBeforeAdd`, so
+     *     this method skips kCamera to avoid duplicate setter invocation.
+     *   - Update path (oldMediaSource is provided): kCamera goes through the
+     *     same diff check as other types and is dispatched only when changed.
+     *
+     * @param mediaSource - The new media source carrying capture params.
+     * @param oldMediaSource - The previous media source (omit for the add path
+     *                         where no previous params exist; in that case the
+     *                         setter is always invoked when params are present).
+     */
+    private _applyMediaSourceParams;
+    /**
+     * @private
+     * Shallow-but-stable equality check on capture param objects via JSON.
+     *
+     * Returns true when both sides represent the "same" params, false otherwise.
+     * Semantics:
+     *   - both empty (undefined / null) → true (no change requested)
+     *   - exactly one side empty → false (first-time apply or transition)
+     *   - both non-empty → byte-equal after JSON.stringify
+     *
+     * Note: JSON.stringify is sensitive to key ordering. Capture param objects
+     * carried by `TRTCMediaSource` are constructed by the SDK via
+     * `JSON.parse(JSON.stringify(...))` flow, so key order is stable in
+     * practice; for caller-supplied literal objects with unstable key order,
+     * the comparison may yield a false-negative and trigger an unnecessary
+     * setter call.
+     */
+    private _isSameCaptureParams;
     private previewInNativeWindow;
     private previewInWebElement;
     private previewInNone;
+    /**
+     * @private
+     * Ensure the media server is running in the mode required by the current
+     * preview target, before doing any preview binding.
+     *
+     *   - Native-window preview  -> Independent server (out-of-process, comes
+     *     with onMediaServerState crash monitoring & auto-recovery).
+     *   - Web-element preview     -> Embedded server (in-process) that drives
+     *     the video-frame render callback.
+     *
+     * The decision is driven by `serverStatus` (the single source of truth),
+     * NOT by `serverMode`. `serverMode` only reflects the mode of a *running*
+     * server and becomes meaningless once the server is stopped (Idle), where
+     * it keeps its last value. Keying the switch on `serverStatus` avoids that
+     * stale-value trap:
+     *
+     *   - running (Started/Starting) in a different mode -> stop then restart in
+     *     the required mode (mode switch).
+     *   - running already in the required mode           -> no-op.
+     *   - Idle (e.g. after stopMediaMixingServer on logout) -> (re)start in the
+     *     required mode. Without this, a logout -> login cycle would leave no
+     *     monitored server, so a later crash of liteav_media_server.exe emits no
+     *     state=3 event and neither the SDK's built-in recovery nor the app-layer
+     *     recovery runs.
+     *
+     * `Lost` handling depends on autoControlServer, so the two recovery paths
+     * never overlap / race:
+     *
+     *   - autoControlServer = true  (getMediaMixingManager): the SDK owns crash
+     *     recovery via onMediaServerState(state=3) -> recoverMediaMixingServer,
+     *     which restarts the server AND re-binds the preview itself. We must NOT
+     *     also restart here, otherwise a concurrent app-driven bindPreviewArea
+     *     would double-start the server and race the built-in recovery. So when
+     *     autoControlServer is true, `Lost` is intentionally left untouched here.
+     *
+     *   - autoControlServer = false (getMediaMixingService): the SDK does NOT
+     *     auto-recover (onMediaMixingServerLost only clears local state); the app
+     *     is expected to drive recovery by calling bindPreviewArea again. In that
+     *     case a `Lost` server must be (re)started here, exactly like `Idle`,
+     *     otherwise the app's re-bind would silently do nothing and the preview
+     *     would never come back.
+     *
+     * Safe against the first-launch path: startMediaMixingServer sets
+     * serverStatus to Starting synchronously, and the constructor's embedded
+     * auto-start runs before any bindPreviewArea, so the first bind never
+     * observes Idle here.
+     */
+    private ensureMediaServerMode;
     private createWebRenderer;
     private destroyWebRenderer;
     private createWebRendererBuffer;

package/liteav/extensions/MediaMixingManager/MediaMixingManager.js

@@ -92,6 +92,21 @@ const TRTCMediaSourceType_HACK_JSDOC = {
  *
  */
 const TRTCPhoneMirrorParam_HACK_JSDOC = null;
+/**
+ * 在线视频播放参数
+ *
+ * @typedef {Object} TRTCOnlineVideoParam
+ * @property {Number} networkCacheSizeKB 网络缓存大小，单位 KB
+ * @property {Number} playoutVolume 播放音量，取值 0 - 100
+ */
+const TRTCOnlineVideoParam_HACK_JSDOC = null;
+/**
+ * 本地视频文件播放参数
+ *
+ * @typedef {Object} TRTCVideoFileParam
+ * @property {Number} playoutVolume 播放音量，取值 0 - 100
+ */
+const TRTCVideoFileParam_HACK_JSDOC = null;
 /**
  * 媒体源数据
  *
@@ -99,12 +114,16 @@ const TRTCPhoneMirrorParam_HACK_JSDOC = null;
  * @property {TRTCMediaSourceType} sourceType 媒体源类型
  * @property {String} sourceId 媒体源唯一 ID
  * @property {Number} zOrder 媒体源展示层级，取值 0 - 15
+ * @property {Boolean} enableGreenScreen 是否开启绿幕（仅在 sourceType 为 kCamera 时生效），可选属性
  * @property {Rect} rect 媒体源显示区域
  * @property {Boolean} isSelected 媒体源是否选中，可选属性，默认：false
  * @property {TRTCVideoRotation} rotation 媒体源选中角度，可选属性
  * @property {TRTCVideoFillMode} fillMode 媒体源显示模式，可选属性，默认 `TRTCVideoFillMode_Fit`
  * @property {TRTCVideoMirrorType} mirrorType 媒体源是否镜像，可选属性，默认不镜像
- * @property {TRTCPhoneMirrorConnectionParam} connectionParam 手机投屏类型媒体源，连接参数
+ * @property {TRTCCameraCaptureParams} camera 摄像头采集参数，仅在 sourceType 为 kCamera 时生效，可选属性
+ * @property {TRTCScreenCaptureProperty} screen 屏幕/窗口采集属性，仅在 sourceType 为 kScreen 时生效，可选属性
+ * @property {TRTCVideoFileParam} localVideo 本地视频文件播放参数，仅在 sourceType 为 kVideoFile 时生效，可选属性
+ * @property {TRTCOnlineVideoParam} onlineVideo 在线视频播放参数，仅在 sourceType 为 kOnlineVideo 时生效，可选属性
  */
 const TRTCMediaSource_HACK_JSDOC = null;
 /**
@@ -133,20 +152,20 @@ const TRTCStreamLayoutMode_HACK_JSDOC = {
  * 单路连麦视频流布局信息
  *
  * 本地混流高性能渲染模式下，单路视频流布局信息
- * @typedef {Object} TRTCStreamInfo
+ * @typedef {Object} TRTCUserStream
  * @property {String} userId 用户 ID，本地用户需填空字符长
  * @property {TRTCVideoFillMode} fillMode 视频填充模式
  * @property {Rect} rect 视频流显示区域
  * @property {Number} zOrder 视频流展示层级，取值 0 - 15
  */
-const TRTCStreamInfo_HACK_JSDOC = null;
+const TRTCUserStream_HACK_JSDOC = null;
 /**
  * 连麦视频流布局信息
  *
  * 本地混流高性能渲染模式下，所有视频流布局信息
  * @typedef {Object} TRTCStreamLayout
  * @property {TRTCStreamLayoutMode} layoutMode 布局模式
- * @property {Array<TRTCStreamInfo>} userList 非必填，用户视频流布局
+ * @property {Array<TRTCUserStream>} userList 非必填，用户视频流布局
  */
 const TRTCStreamLayout_HACK_JSDOC = null;
 const initResolutionMap = () => {
@@ -217,6 +236,8 @@ var TRTCMediaMixingEvent;
     TRTCMediaMixingEvent["onError"] = "onError";
     /**
      * @description 设备插入事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourcePlugged
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -225,6 +246,8 @@ var TRTCMediaMixingEvent;
     TRTCMediaMixingEvent["onSourcePlugged"] = "onSourcePlugged";
     /**
      * @description 设备链接事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceConnected
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -233,6 +256,8 @@ var TRTCMediaMixingEvent;
     TRTCMediaMixingEvent["onSourceConnected"] = "onSourceConnected";
     /**
      * @description 设备断开链接事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceDisconnected
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -241,6 +266,8 @@ var TRTCMediaMixingEvent;
     TRTCMediaMixingEvent["onSourceDisconnected"] = "onSourceDisconnected";
     /**
      * @description 设备拔出事件
+     * @deprecated
+     * @private
      *
      * @event TRTCMediaMixingEvent#onSourceUnplugged
      * @param {TRTCPhoneMirrorParam} source 投屏手机状态信息
@@ -258,6 +285,13 @@ var TRTCMediaMixingEvent;
      * @param {Number} size.height 媒体源最新高度
      */
     TRTCMediaMixingEvent["onMediaSourceSizeChanged"] = "onMediaSourceSizeChanged";
+    /**
+     * @description 本地混流服务丢失事件
+     * @deprecated
+     * @private
+     *
+     * @event TRTCMediaMixingEvent#onMediaMixingServerLost
+     */
     TRTCMediaMixingEvent["onMediaMixingServerLost"] = "onMediaMixingServerLost";
 })(TRTCMediaMixingEvent = exports.TRTCMediaMixingEvent || (exports.TRTCMediaMixingEvent = {}));
 const promiseKeys = {
@@ -323,6 +357,7 @@ class TRTCMediaMixingManager {
         this.nodeTRTCCloud = options.nodeTRTCCloud;
         this.trtcParamsStore = options.trtcParamsStore;
         this.autoControlServer = options.autoControlServer;
+        this.pluginManager = options.pluginManager;
         this.paramsStore = {};
         this.previewRenderParams = {
             fillMode: trtc_define_1.TRTCVideoFillMode.TRTCVideoFillMode_Fit,
@@ -398,6 +433,8 @@ class TRTCMediaMixingManager {
             this.addMediaSourceTimers.clear();
             this.paramsStore = null;
             this.trtcParamsStore = null;
+            // 仅解除引用，pluginManager 生命周期由 TRTCCloud 统一管理
+            this.pluginManager = null;
         });
     }
     /**
@@ -598,6 +635,10 @@ class TRTCMediaMixingManager {
                     }
                 }, timeoutMs);
                 this.addMediaSourceTimers.set(key, timer);
+                // Apply camera capture params BEFORE native addMediaSource to avoid an
+                // extra camera restart on first add. Other source types are handled in
+                // the onMediaSourceAdded callback once the C++ layer reports success.
+                this._applyCameraParamsBeforeAdd(newMediaSource);
                 this.nodeMediaMixingPlugin.addMediaSource(newMediaSource);
                 (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.addMedia({
                     id: `${newMediaSource.sourceType}__${newMediaSource.sourceId}`,
@@ -610,13 +651,6 @@ class TRTCMediaMixingManager {
             });
         });
     }
-    /**
-     * Returns the per-sourceType timeout (ms) used by addMediaSource. The
-     * defaults are intentionally larger than the cpp-layer timeout in
-     * SourceManagerProxy so that, in the normal case, the cpp side resolves the
-     * promise first. This JS timer is the last-resort safety net in case the
-     * cpp side itself fails to emit any callback (older builds, ipc lost, etc.).
-     */
     getAddMediaSourceTimeoutMs(sourceType) {
         switch (sourceType) {
             case types_1.TRTCMediaSourceType.kOnlineVideo:
@@ -701,6 +735,7 @@ class TRTCMediaMixingManager {
                 }
             }
             yield this.nodeMediaMixingPlugin.updateMediaSource(newMediaSource);
+            this._applyMediaSourceParams(newMediaSource, this.sourceList[index]);
             (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.updateMedia({
                 id: `${mediaSource.sourceType}__${mediaSource.sourceId}`,
                 rect: mediaSource.rect,
@@ -713,6 +748,9 @@ class TRTCMediaMixingManager {
     }
     /**
      * 设置摄像头采集参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param cameraID {string} - 摄像头 ID
      * @param params {TRTCCameraCaptureParams} - 摄像头采集参数
      */
@@ -731,6 +769,8 @@ class TRTCMediaMixingManager {
     }
     /**
      * 设置手机投屏参数
+     *
+     * @deprecated
      * @private
      * @param phoneMirrorSourceId {string} - 手机投屏媒体源 ID
      * @param param {TRTCPhoneMirrorParam} - 手机投屏参数
@@ -740,6 +780,9 @@ class TRTCMediaMixingManager {
     }
     /**
      * 设置屏幕采集参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param screenOrWindowID {String} - 屏幕 ID 或 窗口 ID
      * @param property {TRTCScreenCaptureProperty} - 屏幕采集属性
      */
@@ -748,6 +791,9 @@ class TRTCMediaMixingManager {
     }
     /**
      * 设置在线视频源播放参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param url {string} - 在线视频源 URL
      * @param param {TRTCOnlineVideoParam} - 在线视频源播放参数
      */
@@ -756,6 +802,9 @@ class TRTCMediaMixingManager {
     }
     /**
      * 设置视频文件播放参数
+     *
+     * @deprecated 请使用 `addMediaSource` 或 `updateMediaSource` 代替
+     *
      * @param videoFilePath {string} - 视频文件路径
      * @param param {TRTCVideoFileParam} - 视频文件播放参数
      */
@@ -1294,6 +1343,13 @@ class TRTCMediaMixingManager {
         }
         let flag = false;
         if (data.errCode === 0) {
+            const addedIndex = this.findMediaSourceIndex({
+                sourceId: data.sourceId,
+                sourceType: data.sourceType,
+            });
+            if (addedIndex !== -1) {
+                this._applyMediaSourceParams(this.sourceList[addedIndex]);
+            }
             flag = this.promiseStore.resolvePromise(promiseKey, undefined);
         }
         else {
@@ -1434,42 +1490,71 @@ class TRTCMediaMixingManager {
             else {
                 this.sourceList = [];
                 (_a = this.mediaMixingDesigner) === null || _a === void 0 ? void 0 : _a.removeAllMedia();
-                (_b = this.eventEmitter) === null || _b === void 0 ? void 0 : _b.emit(TRTCMediaMixingEvent.onMediaMixingServerLost);
             }
+            // Notify the application layer AFTER the internal recovery/cleanup finishes,
+            // regardless of autoControlServer mode. This lets the app perform extra
+            // recovery on top of the SDK's built-in one (e.g. re-applying beauty /
+            // xmagic effect plugins, which the SDK does not restore). Note
+            // recoverMediaMixingServer swallows its own errors, so this emit is always
+            // reached once server-lost handling completes.
+            (_b = this.eventEmitter) === null || _b === void 0 ? void 0 : _b.emit(TRTCMediaMixingEvent.onMediaMixingServerLost);
         });
     }
     onCallExperimentalAPIFinish(data) {
         logger_1.default.log(`${this.logPrefix}onCallExperimentalAPIFinish:`, data);
     }
     recoverMediaMixingServer() {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.view) {
                 return;
             }
             try {
-                yield this.startMediaMixingServer();
+                // Restart the server in the SAME mode as the pre-crash preview target,
+                // derived from windowID the same way bindPreviewArea dispatches:
+                //   - windowID !== 0 -> native-window preview -> Independent
+                //   - windowID === 0 -> web-element  preview -> Embedded
+                // Using the matching mode here makes the subsequent bindPreviewArea ->
+                // ensureMediaServerMode a no-op (server already running in the right
+                // mode), avoiding an extra stop/start process bounce and a transient
+                // window running in the wrong mode. Previously this hardcoded the default
+                // (Independent), so recovering a web-element (Embedded) preview would
+                // start Independent and then immediately stop+restart as Embedded.
+                const recoverMode = this.windowID !== 0
+                    ? TRTCMediaMixingServerMode.Independent
+                    : TRTCMediaMixingServerMode.Embedded;
+                yield this.startMediaMixingServer('', recoverMode);
                 yield this.bindPreviewArea(this.windowID, this.view);
                 yield this.startPublish();
                 yield this.nodeMediaMixingPlugin.updatePublishParams(this.publishParams);
-                if ((_a = this.paramsStore) === null || _a === void 0 ? void 0 : _a.streamLayout) {
+                // 混流服务崩溃重启后，底层 NodeRemoteVideoPluginManager 为全新初始状态，
+                // 需要重放之前通过 setPluginParams 设置的插件参数。
+                const pluginManager = this.pluginManager;
+                const pluginParams = (_a = this.trtcParamsStore) === null || _a === void 0 ? void 0 : _a.pluginParams;
+                if (pluginManager && pluginParams) {
+                    Object.keys(pluginParams).forEach((typeKey) => {
+                        pluginManager.setPluginParams(Number(typeKey), pluginParams[typeKey]);
+                    });
+                }
+                if ((_b = this.paramsStore) === null || _b === void 0 ? void 0 : _b.streamLayout) {
                     this.setStreamLayout(this.paramsStore.streamLayout);
                 }
                 this.sourceList.forEach((item) => {
+                    this._applyCameraParamsBeforeAdd(item);
                     this.nodeMediaMixingPlugin.addMediaSource(item);
                 });
-                if (((_b = this.trtcParamsStore) === null || _b === void 0 ? void 0 : _b.enterRoomParams) && ((_c = this.trtcParamsStore) === null || _c === void 0 ? void 0 : _c.enterRoomScene)) {
+                if (((_c = this.trtcParamsStore) === null || _c === void 0 ? void 0 : _c.enterRoomParams) && ((_d = this.trtcParamsStore) === null || _d === void 0 ? void 0 : _d.enterRoomScene)) {
                     this.nodeTRTCCloud.enterRoom(this.trtcParamsStore.enterRoomParams, this.trtcParamsStore.enterRoomScene);
                 }
-                if ((_d = this.trtcParamsStore) === null || _d === void 0 ? void 0 : _d.localAudioParams) {
-                    if ((_e = this.trtcParamsStore) === null || _e === void 0 ? void 0 : _e.localAudioParams.audioQuality) {
-                        this.nodeTRTCCloud.startLocalAudio((_f = this.trtcParamsStore) === null || _f === void 0 ? void 0 : _f.localAudioParams.audioQuality);
+                if ((_e = this.trtcParamsStore) === null || _e === void 0 ? void 0 : _e.localAudioParams) {
+                    if ((_f = this.trtcParamsStore) === null || _f === void 0 ? void 0 : _f.localAudioParams.audioQuality) {
+                        this.nodeTRTCCloud.startLocalAudio((_g = this.trtcParamsStore) === null || _g === void 0 ? void 0 : _g.localAudioParams.audioQuality);
                     }
-                    if (((_g = this.trtcParamsStore) === null || _g === void 0 ? void 0 : _g.localAudioParams.isMute) !== undefined) {
+                    if (((_h = this.trtcParamsStore) === null || _h === void 0 ? void 0 : _h.localAudioParams.isMute) !== undefined) {
                         this.nodeTRTCCloud.muteLocalAudio(this.trtcParamsStore.localAudioParams.isMute);
                     }
                 }
-                if ((_h = this.trtcParamsStore) === null || _h === void 0 ? void 0 : _h.systemAudioParams) {
+                if ((_j = this.trtcParamsStore) === null || _j === void 0 ? void 0 : _j.systemAudioParams) {
                     if (this.trtcParamsStore.systemAudioParams.isOpen) {
                         this.nodeTRTCCloud.startSystemAudioLoopback(this.trtcParamsStore.systemAudioParams.path || null);
                     }
@@ -1477,9 +1562,9 @@ class TRTCMediaMixingManager {
                         this.nodeTRTCCloud.setSystemAudioLoopbackVolume(this.trtcParamsStore.systemAudioParams.volume);
                     }
                 }
-                if (typeof ((_j = this.trtcParamsStore) === null || _j === void 0 ? void 0 : _j.audioVolumeEvaluationInterval) === 'number') {
-                    const isEnabled = ((_k = this.trtcParamsStore) === null || _k === void 0 ? void 0 : _k.audioVolumeEvaluationInterval) > 0;
-                    const interval = ((_l = this.trtcParamsStore) === null || _l === void 0 ? void 0 : _l.audioVolumeEvaluationInterval) > 0 ? (_m = this.trtcParamsStore) === null || _m === void 0 ? void 0 : _m.audioVolumeEvaluationInterval : 0;
+                if (typeof ((_k = this.trtcParamsStore) === null || _k === void 0 ? void 0 : _k.audioVolumeEvaluationInterval) === 'number') {
+                    const isEnabled = ((_l = this.trtcParamsStore) === null || _l === void 0 ? void 0 : _l.audioVolumeEvaluationInterval) > 0;
+                    const interval = ((_m = this.trtcParamsStore) === null || _m === void 0 ? void 0 : _m.audioVolumeEvaluationInterval) > 0 ? (_o = this.trtcParamsStore) === null || _o === void 0 ? void 0 : _o.audioVolumeEvaluationInterval : 0;
                     this.nodeTRTCCloud.enableAudioVolumeEvaluation(isEnabled, {
                         enableSpectrumCalculation: isEnabled,
                         enableVadDetection: true,
@@ -1497,17 +1582,115 @@ class TRTCMediaMixingManager {
         logger_1.default.debug(`${this.logPrefix}onDevicePixelRatioChange:`, window.devicePixelRatio);
         this.setDisplayRect();
     }
-    previewInNativeWindow(viewOrRegion) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.serverMode === TRTCMediaMixingServerMode.Embedded && (this.serverStatus === TRTCMediaMixingServerStatus.Started || this.serverStatus === TRTCMediaMixingServerStatus.Starting)) {
-                try {
-                    yield this.stopMediaMixingServer();
-                    yield this.startMediaMixingServer('', TRTCMediaMixingServerMode.Independent);
+    /**
+     * @private
+     * Apply camera capture params BEFORE native addMediaSource.
+     *
+     * Calling setCameraCaptureParam after the camera has already been added
+     * triggers an extra camera restart (the camera first starts with default
+     * params and then restarts with the new ones). To avoid this we set
+     * camera params up-front for the add path. For all other source types
+     * the corresponding setters are dispatched in the post-add callback
+     * (`onMediaSourceAdded` -> `_applyMediaSourceParams`).
+     */
+    _applyCameraParamsBeforeAdd(mediaSource) {
+        if (mediaSource.sourceType === types_1.TRTCMediaSourceType.kCamera && mediaSource.camera) {
+            this.setCameraCaptureParam(mediaSource.sourceId, mediaSource.camera);
+        }
+    }
+    /**
+     * @private
+     * Apply capture params from TRTCMediaSource to the native plugin.
+     *
+     * This method is called after media source is added or updated. To avoid
+     * costly side-effects of native setters (e.g. setCameraCaptureParam will
+     * restart the camera), the setter is invoked only when params are actually
+     * provided AND differ from the previous value carried by `oldMediaSource`.
+     *
+     * Camera handling differs by phase:
+     *   - Add path (oldMediaSource is undefined): camera params have been set
+     *     before native addMediaSource via `_applyCameraParamsBeforeAdd`, so
+     *     this method skips kCamera to avoid duplicate setter invocation.
+     *   - Update path (oldMediaSource is provided): kCamera goes through the
+     *     same diff check as other types and is dispatched only when changed.
+     *
+     * @param mediaSource - The new media source carrying capture params.
+     * @param oldMediaSource - The previous media source (omit for the add path
+     *                         where no previous params exist; in that case the
+     *                         setter is always invoked when params are present).
+     */
+    _applyMediaSourceParams(mediaSource, oldMediaSource) {
+        switch (mediaSource.sourceType) {
+            case types_1.TRTCMediaSourceType.kCamera:
+                // Skip kCamera on the add path to avoid an extra camera restart;
+                // it has been handled by `_applyCameraParamsBeforeAdd` already.
+                if (oldMediaSource && mediaSource.camera && !this._isSameCaptureParams(mediaSource.camera, oldMediaSource.camera)) {
+                    this.setCameraCaptureParam(mediaSource.sourceId, mediaSource.camera);
                 }
-                catch (err) {
-                    logger_1.default.error(`${this.logPrefix}previewInNativeWindow startMediaMixingServer failed:`, err);
-                    throw err;
+                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);
+                }
+                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);
+                }
+                break;
+            case types_1.TRTCMediaSourceType.kVideoFile:
+                if (mediaSource.localVideo && !this._isSameCaptureParams(mediaSource.localVideo, oldMediaSource === null || oldMediaSource === void 0 ? void 0 : oldMediaSource.localVideo)) {
+                    this.setVideoFileParam(mediaSource.sourceId, mediaSource.localVideo);
                 }
+                break;
+        }
+    }
+    /**
+     * @private
+     * Shallow-but-stable equality check on capture param objects via JSON.
+     *
+     * Returns true when both sides represent the "same" params, false otherwise.
+     * Semantics:
+     *   - both empty (undefined / null) → true (no change requested)
+     *   - exactly one side empty → false (first-time apply or transition)
+     *   - both non-empty → byte-equal after JSON.stringify
+     *
+     * Note: JSON.stringify is sensitive to key ordering. Capture param objects
+     * carried by `TRTCMediaSource` are constructed by the SDK via
+     * `JSON.parse(JSON.stringify(...))` flow, so key order is stable in
+     * practice; for caller-supplied literal objects with unstable key order,
+     * the comparison may yield a false-negative and trigger an unnecessary
+     * setter call.
+     */
+    _isSameCaptureParams(next, prev) {
+        if (next === prev) {
+            return true;
+        }
+        const nextEmpty = next === undefined || next === null;
+        const prevEmpty = prev === undefined || prev === null;
+        if (nextEmpty && prevEmpty) {
+            return true;
+        }
+        if (nextEmpty || prevEmpty) {
+            return false;
+        }
+        try {
+            return JSON.stringify(next) === JSON.stringify(prev);
+        }
+        catch (err) {
+            logger_1.default.warn(`${this.logPrefix}_isSameCaptureParams: stringify failed, treat as different.`, err);
+            return false;
+        }
+    }
+    previewInNativeWindow(viewOrRegion) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield this.ensureMediaServerMode(TRTCMediaMixingServerMode.Independent);
+            }
+            catch (err) {
+                logger_1.default.error(`${this.logPrefix}previewInNativeWindow ensureMediaServerMode failed:`, err);
+                throw err;
             }
             if (viewOrRegion instanceof HTMLElement) {
                 if (this.view !== viewOrRegion) {
@@ -1530,19 +1713,22 @@ class TRTCMediaMixingManager {
                 this.destroyDesigner();
                 this.nodeMediaMixingPlugin.setDisplayParams(this.windowID, viewOrRegion);
             }
+            if (!((_a = this.paramsStore) === null || _a === void 0 ? void 0 : _a.streamLayout)) {
+                this.setStreamLayout({
+                    layoutMode: types_1.TRTCStreamLayoutMode.None,
+                });
+            }
         });
     }
     previewInWebElement(viewOrRegion) {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
-            if (this.serverMode === TRTCMediaMixingServerMode.Independent && (this.serverStatus === TRTCMediaMixingServerStatus.Started || this.serverStatus === TRTCMediaMixingServerStatus.Starting)) {
-                try {
-                    yield this.stopMediaMixingServer();
-                    yield this.startMediaMixingServer('', TRTCMediaMixingServerMode.Embedded);
-                }
-                catch (err) {
-                    logger_1.default.error(`${this.logPrefix}previewInWebElement startMediaMixingServer failed:`, err);
-                    throw err;
-                }
+            try {
+                yield this.ensureMediaServerMode(TRTCMediaMixingServerMode.Embedded);
+            }
+            catch (err) {
+                logger_1.default.error(`${this.logPrefix}previewInWebElement ensureMediaServerMode failed:`, err);
+                throw err;
             }
             if (viewOrRegion instanceof HTMLElement) {
                 if (this.view !== viewOrRegion) {
@@ -1559,6 +1745,11 @@ class TRTCMediaMixingManager {
                         this.createDesigner();
                     }
                 }
+                if (!((_a = this.paramsStore) === null || _a === void 0 ? void 0 : _a.streamLayout)) {
+                    this.setStreamLayout({
+                        layoutMode: types_1.TRTCStreamLayoutMode.None,
+                    });
+                }
             }
             else {
                 // neither native window nor web element, stop preview
@@ -1567,12 +1758,83 @@ class TRTCMediaMixingManager {
         });
     }
     previewInNone() {
+        var _a;
         this.destroyResizeObserver();
         this.destroyLayoutManager();
         this.destroyDesigner();
         this.destroyWebRenderer();
         this.view = null;
         this.nodeMediaMixingPlugin.setDisplayParams(this.windowID, { left: 0, right: 0, top: 0, bottom: 0 });
+        if ((_a = this.paramsStore) === null || _a === void 0 ? void 0 : _a.streamLayout) {
+            this.paramsStore.streamLayout = null;
+        }
+    }
+    /**
+     * @private
+     * Ensure the media server is running in the mode required by the current
+     * preview target, before doing any preview binding.
+     *
+     *   - Native-window preview  -> Independent server (out-of-process, comes
+     *     with onMediaServerState crash monitoring & auto-recovery).
+     *   - Web-element preview     -> Embedded server (in-process) that drives
+     *     the video-frame render callback.
+     *
+     * The decision is driven by `serverStatus` (the single source of truth),
+     * NOT by `serverMode`. `serverMode` only reflects the mode of a *running*
+     * server and becomes meaningless once the server is stopped (Idle), where
+     * it keeps its last value. Keying the switch on `serverStatus` avoids that
+     * stale-value trap:
+     *
+     *   - running (Started/Starting) in a different mode -> stop then restart in
+     *     the required mode (mode switch).
+     *   - running already in the required mode           -> no-op.
+     *   - Idle (e.g. after stopMediaMixingServer on logout) -> (re)start in the
+     *     required mode. Without this, a logout -> login cycle would leave no
+     *     monitored server, so a later crash of liteav_media_server.exe emits no
+     *     state=3 event and neither the SDK's built-in recovery nor the app-layer
+     *     recovery runs.
+     *
+     * `Lost` handling depends on autoControlServer, so the two recovery paths
+     * never overlap / race:
+     *
+     *   - autoControlServer = true  (getMediaMixingManager): the SDK owns crash
+     *     recovery via onMediaServerState(state=3) -> recoverMediaMixingServer,
+     *     which restarts the server AND re-binds the preview itself. We must NOT
+     *     also restart here, otherwise a concurrent app-driven bindPreviewArea
+     *     would double-start the server and race the built-in recovery. So when
+     *     autoControlServer is true, `Lost` is intentionally left untouched here.
+     *
+     *   - autoControlServer = false (getMediaMixingService): the SDK does NOT
+     *     auto-recover (onMediaMixingServerLost only clears local state); the app
+     *     is expected to drive recovery by calling bindPreviewArea again. In that
+     *     case a `Lost` server must be (re)started here, exactly like `Idle`,
+     *     otherwise the app's re-bind would silently do nothing and the preview
+     *     would never come back.
+     *
+     * Safe against the first-launch path: startMediaMixingServer sets
+     * serverStatus to Starting synchronously, and the constructor's embedded
+     * auto-start runs before any bindPreviewArea, so the first bind never
+     * observes Idle here.
+     */
+    ensureMediaServerMode(targetMode) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const isRunning = this.serverStatus === TRTCMediaMixingServerStatus.Started
+                || this.serverStatus === TRTCMediaMixingServerStatus.Starting;
+            // `Lost` is treated as "needs (re)start" ONLY when the SDK's own auto
+            // recovery is disabled (autoControlServer=false); otherwise it is owned by
+            // recoverMediaMixingServer and must not be touched here (see doc above).
+            const needsStart = this.serverStatus === TRTCMediaMixingServerStatus.Idle
+                || (this.serverStatus === TRTCMediaMixingServerStatus.Lost && !this.autoControlServer);
+            if (isRunning) {
+                if (this.serverMode !== targetMode) {
+                    yield this.stopMediaMixingServer();
+                    yield this.startMediaMixingServer('', targetMode);
+                }
+            }
+            else if (needsStart) {
+                yield this.startMediaMixingServer('', targetMode);
+            }
+        });
     }
     createWebRenderer(view) {
         if (this.view === view) {
@@ -1603,7 +1865,7 @@ class TRTCMediaMixingManager {
             });
             this.webRenderer.setContentMode(this.previewRenderParams.fillMode);
             this.createWebRendererBuffer();
-            this.nodeMediaMixingPlugin.setVideoFrameRenderCallback(this.webRendererCallback); // this.pixelFormat, 
+            this.nodeMediaMixingPlugin.setVideoFrameRenderCallback(this.webRendererCallback); // this.pixelFormat,
         }
     }
     destroyWebRenderer() {
@@ -1611,7 +1873,7 @@ class TRTCMediaMixingManager {
             this.webRenderer.destroy();
             this.webRenderer = null;
         }
-        this.nodeMediaMixingPlugin.setVideoFrameRenderCallback(null); // this.pixelFormat, 
+        this.nodeMediaMixingPlugin.setVideoFrameRenderCallback(null); // this.pixelFormat,
         this.destroyWebRendererBuffer();
     }
     createWebRendererBuffer() {

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

@@ -39,6 +39,13 @@ export declare type TRTCPhoneMirrorParam = {
     frameRate: number;
     bitrateKbps: number;
 };
+export declare type TRTCOnlineVideoParam = {
+    networkCacheSizeKB: number;
+    playoutVolume: number;
+};
+export declare type TRTCVideoFileParam = {
+    playoutVolume: number;
+};
 export declare type TRTCMediaSource = {
     sourceType: TRTCMediaSourceType;
     sourceId: string;
@@ -49,6 +56,10 @@ export declare type TRTCMediaSource = {
     rotation?: TRTCVideoRotation;
     fillMode?: TRTCVideoFillMode;
     mirrorType?: TRTCVideoMirrorType;
+    camera?: TRTCCameraCaptureParams;
+    screen?: TRTCScreenCaptureProperty;
+    localVideo?: TRTCVideoFileParam;
+    onlineVideo?: TRTCOnlineVideoParam;
 };
 export declare type TRTCMediaMixingEncParam = {
     videoEncoderParams: TRTCVideoEncParam;
@@ -83,20 +94,10 @@ export declare type TRTCStreamLayout = {
     };
     streams?: Array<TRTCStreamInfo>;
 };
-export declare type TRTCOnlineVideoParam = {
-    networkCacheSizeKB: number;
-    playoutVolume: number;
-};
-export declare type TRTCVideoFileParam = {
-    playoutVolume: number;
-};
 export interface ITRTCMediaMixingManager {
     addMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
     removeMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
     updateMediaSource(mediaSource: TRTCMediaSource): Promise<void>;
-    setCameraCaptureParam(cameraID: string, param: TRTCCameraCaptureParams): void;
-    setPhoneMirrorParam(phoneMirrorSourceId: string, param: TRTCPhoneMirrorParam): void;
-    setScreenCaptureProperty(screenWindowID: string, property: TRTCScreenCaptureProperty): void;
     startPublish(): Promise<void>;
     stopPublish(): Promise<void>;
     updatePublishParams(params: TRTCMediaMixingEncParam): Promise<void>;

package/liteav/trtc.js

@@ -4939,6 +4939,9 @@ class TRTCCloud extends events_1.EventEmitter {
     setPluginParams(type, options) {
         this.logger.log(`setPluginParams params:`, type, options);
         this.pluginManager.setPluginParams(type, options);
+        // 记录插件参数，用于本地混流服务崩溃恢复时重放（合并写入，兼容分次只传 pixelFormat 或 enable 的调用）
+        this.paramsStore.pluginParams = this.paramsStore.pluginParams || {};
+        this.paramsStore.pluginParams[type] = Object.assign(Object.assign({}, (this.paramsStore.pluginParams[type] || {})), options);
     }
     /**
      * 添加插件
@@ -5434,6 +5437,10 @@ class TRTCCloud extends events_1.EventEmitter {
         try {
             const json = JSON.parse(jsonStr);
             const { api, params } = json;
+            if (this._isMacPlatform() && api === 'TuikitLog') {
+                this.logger.info(`TuikitLog: ${jsonStr}`);
+                return;
+            }
             if (this[api] && typeof this[api] === 'function') {
                 this[api](params);
             }
@@ -5564,6 +5571,7 @@ class TRTCCloud extends events_1.EventEmitter {
                     nodeTRTCCloud: this.rtcCloud,
                     trtcParamsStore: this.paramsStore,
                     autoControlServer: true,
+                    pluginManager: this.pluginManager,
                 });
             }
         }
@@ -5613,6 +5621,7 @@ class TRTCCloud extends events_1.EventEmitter {
                         nodeTRTCCloud: this.rtcCloud,
                         trtcParamsStore: this.paramsStore,
                         autoControlServer: false,
+                        pluginManager: this.pluginManager,
                     });
                     this.mediaMixingService = new MediaMixingManager_1.TRTCMediaMixingService(this.mediaMixingManager);
                 }

package/package.json

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

package/scripts/download.js

@@ -111,9 +111,17 @@ async function main(urlDomain) {
     await download(downloadUrl, outputDir, downloadOptions);
     signale.success(`Download finished - ${platform}`);
 
+    // Preserve symlinks when copying on macOS so that .framework bundles
+    // retain their canonical Versions/Current -> A symlink structure.
+    // Without { dereference: false }, fs-extra resolves symlinks to real
+    // files/directories, causing `codesign` to report:
+    //   "bundle format is ambiguous (could be app or framework)"
+    const macCopyOptions = { dereference: false };
+
     fs.copySync(
       path.join(outputDir, "./build/Release"),
-      path.join(buildDir, "Release")
+      path.join(buildDir, "Release"),
+      macCopyOptions
     );
     signale.success(`copy success! - ${platform}`);
 
@@ -125,11 +133,13 @@ async function main(urlDomain) {
       const arch = archType;
       fs.copySync(
         path.join(outputDir, "./build/Release/trtc_electron_sdk.node"),
-        path.join(buildDir, "Release", arch, "trtc_electron_sdk.node")
+        path.join(buildDir, "Release", arch, "trtc_electron_sdk.node"),
+        macCopyOptions
       );
       fs.copySync(
         path.join(outputDir, "./build/mac-framework", arch),
-        path.join(buildDir, "mac-framework", arch)
+        path.join(buildDir, "mac-framework", arch),
+        macCopyOptions
       );
       signale.success(`copy success! - mac ${arch}`, "\n");
 
@@ -163,7 +173,8 @@ async function main(urlDomain) {
           "Release",
           anotherArch,
           "trtc_electron_sdk.node"
-        )
+        ),
+        macCopyOptions
       );
       fs.copySync(
         path.join(
@@ -172,7 +183,8 @@ async function main(urlDomain) {
           "/build/mac-framework",
           anotherArch
         ),
-        path.join(buildDir, "mac-framework", anotherArch)
+        path.join(buildDir, "mac-framework", anotherArch),
+        macCopyOptions
       );
       signale.success(`copy success! - mac ${anotherArch}`);