fcr-core 3.10.2 → 3.11.0-rc.2

package/lib/room-control/user-control/index.js

@@ -35,6 +35,7 @@ var _logger = require("../../utilities/logger");
 var _error = require("../../utilities/error");
 var _validateParams = _interopRequireDefault(require("../../utilities/validate-params"));
 var _schema = require("../../schema");
+var _constants = require("../helpers/constants");
 let _initProto, _getUserDecs, _fetchUserListDecs, _updateUserNameDecs, _updateUserPropertiesDecs, _updateIncrementUserPropertiesDecs, _deleteUserPropertiesDecs, _getUserPropertiesByUserIdDecs, _getUserPropertiesByKeyPathDecs, _updateRemoteUserRoleDecs, _claimHostDecs, _kickOutDecs, _kickOutByUserIdsDecs, _kickOutByUserRolesDecs, _mergeAudioStreamDecs;
 function _applyDecs(e, t, r, n, o, a) { function i(e, t, r) { return function (n, o) { return r && r(n), e[t].call(n, o); }; } function c(e, t) { for (var r = 0; r < e.length; r++) e[r].call(t); return t; } function s(e, t, r, n) { if ("function" != typeof e && (n || void 0 !== e)) throw new TypeError(t + " must " + (r || "be") + " a function" + (n ? "" : " or undefined")); return e; } function applyDec(e, t, r, n, o, a, c, u, l, f, p, d, h) { function m(e) { if (!h(e)) throw new TypeError("Attempted to access private element on non-instance"); } var y, v = t[0], g = t[3], b = !u; if (!b) { r || Array.isArray(v) || (v = [v]); var w = {}, S = [], A = 3 === o ? "get" : 4 === o || d ? "set" : "value"; f ? (p || d ? w = { get: _setFunctionName(function () { return g(this); }, n, "get"), set: function (e) { t[4](this, e); } } : w[A] = g, p || _setFunctionName(w[A], n, 2 === o ? "" : A)) : p || (w = Object.getOwnPropertyDescriptor(e, n)); } for (var P = e, j = v.length - 1; j >= 0; j -= r ? 2 : 1) { var D = v[j], E = r ? v[j - 1] : void 0, I = {}, O = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: n, metadata: a, addInitializer: function (e, t) { if (e.v) throw Error("attempted to call addInitializer after decoration was finished"); s(t, "An initializer", "be", !0), c.push(t); }.bind(null, I) }; try { if (b) (y = s(D.call(E, P, O), "class decorators", "return")) && (P = y);else { var k, F; O.static = l, O.private = f, f ? 2 === o ? k = function (e) { return m(e), w.value; } : (o < 4 && (k = i(w, "get", m)), 3 !== o && (F = i(w, "set", m))) : (k = function (e) { return e[n]; }, (o < 2 || 4 === o) && (F = function (e, t) { e[n] = t; })); var N = O.access = { has: f ? h.bind() : function (e) { return n in e; } }; if (k && (N.get = k), F && (N.set = F), P = D.call(E, d ? { get: w.get, set: w.set } : w[A], O), d) { if ("object" == typeof P && P) (y = s(P.get, "accessor.get")) && (w.get = y), (y = s(P.set, "accessor.set")) && (w.set = y), (y = s(P.init, "accessor.init")) && S.push(y);else if (void 0 !== P) throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0"); } else s(P, (p ? "field" : "method") + " decorators", "return") && (p ? S.push(P) : w[A] = P); } } finally { I.v = !0; } } return (p || d) && u.push(function (e, t) { for (var r = S.length - 1; r >= 0; r--) t = S[r].call(e, t); return t; }), p || b || (f ? d ? u.push(i(w, "get"), i(w, "set")) : u.push(2 === o ? w[A] : i.call.bind(w[A])) : Object.defineProperty(e, n, w)), P; } function u(e, t) { return Object.defineProperty(e, Symbol.metadata || Symbol.for("Symbol.metadata"), { configurable: !0, enumerable: !0, value: t }); } if (arguments.length >= 6) var l = a[Symbol.metadata || Symbol.for("Symbol.metadata")]; var f = Object.create(null == l ? null : l), p = function (e, t, r, n) { var o, a, i = [], s = function (t) { return _checkInRHS(t) === e; }, u = new Map(); function l(e) { e && i.push(c.bind(null, e)); } for (var f = 0; f < t.length; f++) { var p = t[f]; if (Array.isArray(p)) { var d = p[1], h = p[2], m = p.length > 3, y = 16 & d, v = !!(8 & d), g = 0 == (d &= 7), b = h + "/" + v; if (!g && !m) { var w = u.get(b); if (!0 === w || 3 === w && 4 !== d || 4 === w && 3 !== d) throw Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + h); u.set(b, !(d > 2) || d); } applyDec(v ? e : e.prototype, p, y, m ? "#" + h : _toPropertyKey(h), d, n, v ? a = a || [] : o = o || [], i, v, m, g, 1 === d, v && m ? s : r); } } return l(o), l(a), i; }(e, t, o, f); return r.length || u(e, f), { e: p, get c() { var t = []; return r.length && [u(applyDec(e, [r], n, e.name, 5, f, t), f), c.bind(null, t, e)]; } }; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
@@ -172,6 +173,29 @@ class FcrUserControlImpl {
           });
         }
       }
+      if (event.cause?.cmd === _constants.ROOM_MESSAGE_COMMANDS.CLIENT_RECORDING_PERMISSION) {
+        const {
+          changedProperties,
+          modifiedUser
+        } = event;
+        const enable = (0, _imports.get)(changedProperties, 'security.clientRecording');
+        if (Object.keys(changedProperties).length > 0) {
+          this._observable.notifyObservers('onUserClientRecordingPermissionUpdated', modifiedUser.userId, !!enable);
+        }
+      }
+      if (event.cause?.cmd === _constants.ROOM_MESSAGE_COMMANDS.USER_WIDGET_PROPERTIES_UPDATE) {
+        const widgetCauseCmd = event.cause?.data?.widgetCause?.cmd;
+        if (widgetCauseCmd === _constants.ROOM_MESSAGE_COMMANDS.CLIENT_RECORDING_STATE) {
+          const {
+            changedProperties,
+            modifiedUser
+          } = event;
+          const enable = (0, _imports.get)(changedProperties, 'widgets.clientRecording.state');
+          if (Object.keys(changedProperties).length > 0) {
+            this._observable.notifyObservers('onUserClientRecordingStateUpdated', modifiedUser.userId, !!enable);
+          }
+        }
+      }
     },
     onUserPropertiesDeleted: (roomId, event) => {
       if (event.cause?.cmd === 8) {
@@ -262,6 +286,14 @@ class FcrUserControlImpl {
     } = this.getLocalUser();
     return (0, _imports.get)(this._scene.getUserPropertiesByUserId(userId), 'security.watermark.content');
   }
+  getUserClientRecordingState(userId) {
+    const state = (0, _imports.get)(this._scene.getUserPropertiesByUserId(userId), 'widgets.clientRecording.state');
+    return Boolean(state);
+  }
+  getUserClientRecordingPermission(userId) {
+    const permission = (0, _imports.get)(this._scene.getUserPropertiesByUserId(userId), 'security.clientRecording');
+    return Boolean(permission);
+  }
   async fetchUserList(params) {
     return await this._scene.fetchUserList(params);
   }

package/lib/room-control/user-control/type.d.ts

@@ -116,6 +116,18 @@ export interface FcrUserControl {
      * Retrieve the watermark content of the current user
      */
     getWaterMarkContent(): string | undefined;
+    /**
+     * Gets the client recording state of a specific user.
+     * @param userId The user ID to query
+     * @returns true if the user is currently doing client recording, false otherwise
+     */
+    getUserClientRecordingState(userId: string): boolean;
+    /**
+     * Gets the client recording permission of a specific user.
+     * @param userId The user ID to query
+     * @returns true if the user has client recording permission, false otherwise
+     */
+    getUserClientRecordingPermission(userId: string): boolean;
     /**
      * Releases the user control.
      */
@@ -188,6 +200,18 @@ export type FcrUserObserver = {
      * @param event
      */
     onLocalUserKickedOut?(roomId: string, event: FcrUserKickedOutEvent): void;
+    /**
+     * Callback to receive the user client recording permission updated event.
+     * @param userId
+     * @param enable
+     */
+    onUserClientRecordingPermissionUpdated?(userId: string, enable: boolean): void;
+    /**
+     * Callback to receive the user client recording state updated event.
+     * @param userId
+     * @param enable - whether the user is client recording
+     */
+    onUserClientRecordingStateUpdated?(userId: string, enable: boolean): void;
     /**
      * Callback to receive the user count updated by role event.
      * @param roomId

package/lib/room-control/whiteboard-control-v2/base/index.js

@@ -177,8 +177,8 @@ class FcrBaseWhiteboardControlImpl {
         boardAppId,
         boardId,
         boardRegion,
-        boardToken
-        // boardPerformance = false,
+        boardToken,
+        boardPerformance = false
       } = this.boardRoomConfig || {};
       if (!boardAppId) {
         throw (0, _error.generateFcrCoreClientError)(_imports.ErrorModuleCode.FCR_ROOM_WHITEBOARD, _imports.DetailErrorCode.UNDEFINED_ERROR, 'boardAppId is required');
@@ -250,8 +250,8 @@ class FcrBaseWhiteboardControlImpl {
               region: endpoint ? 'private' : boardRegion,
               appIdentifier: boardAppId
             },
-            endpoint,
-            writable: true
+            writable: isNeedLaunch,
+            endpoint
             // verboseLog: true,
           };
           this.logger.info(`Room.joinRoom calling, params: ${(0, _imports.jsonstring)(joinRoomParams)}, timeout: ${WHITEBOARD_ROOM_JOIN_TIMEOUT}`);
@@ -297,14 +297,11 @@ class FcrBaseWhiteboardControlImpl {
         this.whiteboard = whiteboard;
         this.boardView = boardView;
         this.boardRoom = boardRoom;
-
-        // if (isNeedLaunch) {
-        //   // 所有人开启白板时都默认没有开启写权限, 需要写权限的地方需要自己手动开启
-        //   boardView.internalSetWritable(false);
-        // }
-
-        // boardView.setPerformanceMode(boardPerformance);
-
+        if (isNeedLaunch) {
+          // 所有人开启白板时都默认没有开启写权限, 需要写权限的地方需要自己手动开启
+          boardView.internalSetWritable(false);
+        }
+        boardView.setPerformanceMode(boardPerformance);
         this.updateConnectionState(_type.FcrConnectionState.CONNECTED);
         resolve(boardView);
         if (this._waitPromiseResolve) {

package/lib/room-control/whiteboard-control-v2/base/main-window.d.ts

@@ -28,6 +28,12 @@ export declare class FcrBoardMainWindowImpl implements FcrBoardMainWindow {
     redo(): Promise<FcrReturnCode>;
     clean(): Promise<FcrReturnCode>;
     getSnapshotImage(): Promise<ImageData>;
+    /**
+     * 设置性能模式状态, enabled 为 true 时开启性能模式, 否则关闭性能模式
+     * 性能模式下, 白板会降低渲染质量及同步频率以提升性能, 适用于低性能设备或需要大量绘制元素的场景
+     * @param enable 是否开启性能模式
+     */
+    setPerformanceMode(enable: boolean): FcrReturnCode;
     setBackgroundColor(color: string): Promise<FcrReturnCode>;
     getPageInfo(): FcrBoardPageInfo;
     prevPage(): Promise<FcrReturnCode>;

package/lib/room-control/whiteboard-control-v2/base/main-window.js

@@ -33,7 +33,7 @@ var _decorator = require("agora-foundation/lib/decorator");
 var _type = require("../../../type");
 var _error = require("../../../utilities/error");
 var _imports = require("../../../imports");
-let _initProto, _setBackgroundColorDecs, _setToolTypeDecs, _setStrokeWidthDecs, _setStrokeColorDecs, _setTextColorDecs, _setTextSizeDecs, _insertImageDecs, _setContainerSizeRatioDecs, _setBoardTransparentDecs, _updateWindowSizeDecs, _setAutoCancelDrawDecs, _handleApplicationLaunchDecs, _handleApplicationTerminalDecs, _enableAutoCancelDecs;
+let _initProto, _setPerformanceModeDecs, _setBackgroundColorDecs, _setToolTypeDecs, _setStrokeWidthDecs, _setStrokeColorDecs, _setTextColorDecs, _setTextSizeDecs, _insertImageDecs, _setContainerSizeRatioDecs, _setBoardTransparentDecs, _updateWindowSizeDecs, _setAutoCancelDrawDecs, _handleApplicationLaunchDecs, _handleApplicationTerminalDecs, _enableAutoCancelDecs;
 function _applyDecs(e, t, r, n, o, a) { function i(e, t, r) { return function (n, o) { return r && r(n), e[t].call(n, o); }; } function c(e, t) { for (var r = 0; r < e.length; r++) e[r].call(t); return t; } function s(e, t, r, n) { if ("function" != typeof e && (n || void 0 !== e)) throw new TypeError(t + " must " + (r || "be") + " a function" + (n ? "" : " or undefined")); return e; } function applyDec(e, t, r, n, o, a, c, u, l, f, p, d, h) { function m(e) { if (!h(e)) throw new TypeError("Attempted to access private element on non-instance"); } var y, v = t[0], g = t[3], b = !u; if (!b) { r || Array.isArray(v) || (v = [v]); var w = {}, S = [], A = 3 === o ? "get" : 4 === o || d ? "set" : "value"; f ? (p || d ? w = { get: _setFunctionName(function () { return g(this); }, n, "get"), set: function (e) { t[4](this, e); } } : w[A] = g, p || _setFunctionName(w[A], n, 2 === o ? "" : A)) : p || (w = Object.getOwnPropertyDescriptor(e, n)); } for (var P = e, j = v.length - 1; j >= 0; j -= r ? 2 : 1) { var D = v[j], E = r ? v[j - 1] : void 0, I = {}, O = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: n, metadata: a, addInitializer: function (e, t) { if (e.v) throw Error("attempted to call addInitializer after decoration was finished"); s(t, "An initializer", "be", !0), c.push(t); }.bind(null, I) }; try { if (b) (y = s(D.call(E, P, O), "class decorators", "return")) && (P = y);else { var k, F; O.static = l, O.private = f, f ? 2 === o ? k = function (e) { return m(e), w.value; } : (o < 4 && (k = i(w, "get", m)), 3 !== o && (F = i(w, "set", m))) : (k = function (e) { return e[n]; }, (o < 2 || 4 === o) && (F = function (e, t) { e[n] = t; })); var N = O.access = { has: f ? h.bind() : function (e) { return n in e; } }; if (k && (N.get = k), F && (N.set = F), P = D.call(E, d ? { get: w.get, set: w.set } : w[A], O), d) { if ("object" == typeof P && P) (y = s(P.get, "accessor.get")) && (w.get = y), (y = s(P.set, "accessor.set")) && (w.set = y), (y = s(P.init, "accessor.init")) && S.push(y);else if (void 0 !== P) throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0"); } else s(P, (p ? "field" : "method") + " decorators", "return") && (p ? S.push(P) : w[A] = P); } } finally { I.v = !0; } } return (p || d) && u.push(function (e, t) { for (var r = S.length - 1; r >= 0; r--) t = S[r].call(e, t); return t; }), p || b || (f ? d ? u.push(i(w, "get"), i(w, "set")) : u.push(2 === o ? w[A] : i.call.bind(w[A])) : Object.defineProperty(e, n, w)), P; } function u(e, t) { return Object.defineProperty(e, Symbol.metadata || Symbol.for("Symbol.metadata"), { configurable: !0, enumerable: !0, value: t }); } if (arguments.length >= 6) var l = a[Symbol.metadata || Symbol.for("Symbol.metadata")]; var f = Object.create(null == l ? null : l), p = function (e, t, r, n) { var o, a, i = [], s = function (t) { return _checkInRHS(t) === e; }, u = new Map(); function l(e) { e && i.push(c.bind(null, e)); } for (var f = 0; f < t.length; f++) { var p = t[f]; if (Array.isArray(p)) { var d = p[1], h = p[2], m = p.length > 3, y = 16 & d, v = !!(8 & d), g = 0 == (d &= 7), b = h + "/" + v; if (!g && !m) { var w = u.get(b); if (!0 === w || 3 === w && 4 !== d || 4 === w && 3 !== d) throw Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + h); u.set(b, !(d > 2) || d); } applyDec(v ? e : e.prototype, p, y, m ? "#" + h : _toPropertyKey(h), d, n, v ? a = a || [] : o = o || [], i, v, m, g, 1 === d, v && m ? s : r); } } return l(o), l(a), i; }(e, t, o, f); return r.length || u(e, f), { e: p, get c() { var t = []; return r.length && [u(applyDec(e, [r], n, e.name, 5, f, t), f), c.bind(null, t, e)]; } }; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
@@ -41,9 +41,9 @@ function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.descrip
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 class FcrBoardMainWindowImpl {
   static {
-    [_initProto] = _applyDecs(this, [[_log.trace, 2, "addPage"], [_log.trace, 2, "removePage"], [_log.trace, 2, "undo"], [_log.trace, 2, "redo"], [_log.trace, 2, "clean"], [_log.trace, 2, "getSnapshotImage"], [_setBackgroundColorDecs, 2, "setBackgroundColor"], [_log.trace, 2, "getPageInfo"], [_log.trace, 2, "prevPage"], [_log.trace, 2, "nextPage"], [_setToolTypeDecs, 2, "setToolType"], [_setStrokeWidthDecs, 2, "setStrokeWidth"], [_setStrokeColorDecs, 2, "setStrokeColor"], [_setTextColorDecs, 2, "setTextColor"], [_setTextSizeDecs, 2, "setTextSize"], [_insertImageDecs, 2, "insertImage"], [_log.trace, 2, "getContentView"], [_setContainerSizeRatioDecs, 2, "setContainerSizeRatio"], [_setBoardTransparentDecs, 2, "setBoardTransparent"], [_updateWindowSizeDecs, 2, "updateWindowSize"], [_setAutoCancelDrawDecs, 2, "setAutoCancelDraw"], [_log.trace, 2, "getWritable"], [_handleApplicationLaunchDecs, 2, "_handleApplicationLaunch"], [_handleApplicationTerminalDecs, 2, "_handleApplicationTerminal"], [_enableAutoCancelDecs, 2, "_enableAutoCancel"]], []).e;
+    [_initProto] = _applyDecs(this, [[_log.trace, 2, "addPage"], [_log.trace, 2, "removePage"], [_log.trace, 2, "undo"], [_log.trace, 2, "redo"], [_log.trace, 2, "clean"], [_log.trace, 2, "getSnapshotImage"], [_setPerformanceModeDecs, 2, "setPerformanceMode"], [_setBackgroundColorDecs, 2, "setBackgroundColor"], [_log.trace, 2, "getPageInfo"], [_log.trace, 2, "prevPage"], [_log.trace, 2, "nextPage"], [_setToolTypeDecs, 2, "setToolType"], [_setStrokeWidthDecs, 2, "setStrokeWidth"], [_setStrokeColorDecs, 2, "setStrokeColor"], [_setTextColorDecs, 2, "setTextColor"], [_setTextSizeDecs, 2, "setTextSize"], [_insertImageDecs, 2, "insertImage"], [_log.trace, 2, "getContentView"], [_setContainerSizeRatioDecs, 2, "setContainerSizeRatio"], [_setBoardTransparentDecs, 2, "setBoardTransparent"], [_updateWindowSizeDecs, 2, "updateWindowSize"], [_setAutoCancelDrawDecs, 2, "setAutoCancelDraw"], [_log.trace, 2, "getWritable"], [_handleApplicationLaunchDecs, 2, "_handleApplicationLaunch"], [_handleApplicationTerminalDecs, 2, "_handleApplicationTerminal"], [_enableAutoCancelDecs, 2, "_enableAutoCancel"]], []).e;
   }
-  [(_setBackgroundColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema.stringSchema)], _setToolTypeDecs = [(0, _log.trace)(['type']), (0, _validateParams.default)(_schema2.fcrBoardToolTypeSchema)], _setStrokeWidthDecs = [(0, _log.trace)(['strokeWidth']), (0, _validateParams.default)(_schema2.numberSchema)], _setStrokeColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema2.z.union([_schema2.colorSchema, _schema.stringSchema]))], _setTextColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema2.colorSchema)], _setTextSizeDecs = [(0, _log.trace)(['textSize']), (0, _validateParams.default)(_schema2.numberSchema)], _insertImageDecs = [(0, _log.trace)(['resourceUrl', 'x', 'y', 'width', 'height']), (0, _validateParams.default)(_schema.stringSchema, _schema2.numberSchema, _schema2.numberSchema, _schema2.numberSchema, _schema2.numberSchema)], _setContainerSizeRatioDecs = [(0, _log.trace)(['ratio']), (0, _validateParams.default)(_schema2.numberSchema)], _setBoardTransparentDecs = [(0, _log.trace)(['isTransparent']), (0, _validateParams.default)(_schema2.booleanSchema)], _updateWindowSizeDecs = [(0, _log.trace)(['size']), (0, _validateParams.default)(_schema2.fcrSizeSchema)], _setAutoCancelDrawDecs = [(0, _log.trace)(['enable']), (0, _validateParams.default)(_schema2.booleanSchema)], _handleApplicationLaunchDecs = [_decorator.bound, (0, _log.trace)(['appId', 'app'])], _handleApplicationTerminalDecs = [_decorator.bound, (0, _log.trace)(['appId', 'app'])], _enableAutoCancelDecs = (0, _log.trace)(['enable']), "logger")] = (_initProto(this), (0, _logger.createLogger)({
+  [(_setPerformanceModeDecs = (0, _log.trace)(['enable']), _setBackgroundColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema.stringSchema)], _setToolTypeDecs = [(0, _log.trace)(['type']), (0, _validateParams.default)(_schema2.fcrBoardToolTypeSchema)], _setStrokeWidthDecs = [(0, _log.trace)(['strokeWidth']), (0, _validateParams.default)(_schema2.numberSchema)], _setStrokeColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema2.z.union([_schema2.colorSchema, _schema.stringSchema]))], _setTextColorDecs = [(0, _log.trace)(['color']), (0, _validateParams.default)(_schema2.colorSchema)], _setTextSizeDecs = [(0, _log.trace)(['textSize']), (0, _validateParams.default)(_schema2.numberSchema)], _insertImageDecs = [(0, _log.trace)(['resourceUrl', 'x', 'y', 'width', 'height']), (0, _validateParams.default)(_schema.stringSchema, _schema2.numberSchema, _schema2.numberSchema, _schema2.numberSchema, _schema2.numberSchema)], _setContainerSizeRatioDecs = [(0, _log.trace)(['ratio']), (0, _validateParams.default)(_schema2.numberSchema)], _setBoardTransparentDecs = [(0, _log.trace)(['isTransparent']), (0, _validateParams.default)(_schema2.booleanSchema)], _updateWindowSizeDecs = [(0, _log.trace)(['size']), (0, _validateParams.default)(_schema2.fcrSizeSchema)], _setAutoCancelDrawDecs = [(0, _log.trace)(['enable']), (0, _validateParams.default)(_schema2.booleanSchema)], _handleApplicationLaunchDecs = [_decorator.bound, (0, _log.trace)(['appId', 'app'])], _handleApplicationTerminalDecs = [_decorator.bound, (0, _log.trace)(['appId', 'app'])], _enableAutoCancelDecs = (0, _log.trace)(['enable']), "logger")] = (_initProto(this), (0, _logger.createLogger)({
     prefix: 'FcrBoardMainWindowImpl'
   }));
   _observable = new _observable.AgoraObservable();
@@ -143,6 +143,16 @@ class FcrBoardMainWindowImpl {
       throw new Error('Whiteboard is not initialized');
     }
   }
+
+  /**
+   * 设置性能模式状态, enabled 为 true 时开启性能模式, 否则关闭性能模式
+   * 性能模式下, 白板会降低渲染质量及同步频率以提升性能, 适用于低性能设备或需要大量绘制元素的场景
+   * @param enable 是否开启性能模式
+   */
+  setPerformanceMode(enable) {
+    this._whiteboard.setPerformanceMode(enable);
+    return _type.FcrReturnCode.SUCCESS;
+  }
   async setBackgroundColor(color) {
     this._background = color;
     this.logger.info(`set canvas background color: ${this._background}`);

package/lib/room-control/whiteboard-control-v2/type.d.ts

@@ -110,6 +110,11 @@ export interface FcrBoardMainWindow {
      * @param textSize
      */
     setTextSize(textSize: number): Promise<number>;
+    /**
+     * Sets the performance mode of the whiteboard.
+     * @param enable Whether to enable performance mode.
+     */
+    setPerformanceMode(enable: boolean): number;
     /**
      * Sets the background color of the whiteboard.
      * @param color

package/lib/service/api.d.ts

@@ -2,7 +2,7 @@ import { AgoraRestfulClient, AgoraRteEntryRoomResponse } from '../imports';
 import { FcrCloudRecordingConfig, FcrGroupCreateConfig, FcrGroupUpdateOptions, FcrLiveStreamingLayoutType, FcrLiveStreamingConfig, FcrSharePermissionProps, FcrAllowWatermarkPayloadBody, FcrAnnotationProps, FcrLanguageConfig, FcrLanguage } from '../type';
 import { AgoraRteRegion } from '../imports';
 import { FcrCheckInParams, FcrChatRoomTokenResData } from './type';
-import { FcrChatPrivilegeConfig, FcrPrivilegeUserRole, FcrPrivilegeUserRoleToStringMap, FcrSecuritySendChatPayload } from '../room-control/privilege-control/type';
+import { FcrChatPrivilegeConfig, FcrPrivilegeUserRole, FcrPrivilegeUserRoleToStringMap, FcrSecuritySendChatPayload, FcrClientRecordingPermissionType } from '../room-control/privilege-control/type';
 import { FcrUserKickedOutType } from '../room-control/user-control/type';
 import { AgoraRteAudioSourceType, AgoraRteMediaPublishState, AgoraRteVideoSourceType } from '../imports';
 import { FcrBoardRoomConfig } from '../room-control/whiteboard-control-v2/type';
@@ -65,6 +65,9 @@ export declare class FcrCoreServiceApi {
     pauseCloudRecording(roomId: string): Promise<any>;
     resumeCloudRecording(roomId: string): Promise<any>;
     stopCloudRecording(roomId: string): Promise<any>;
+    startClientRecording(roomId: string, userId: string): Promise<any>;
+    resumeClientRecording(roomId: string, userId: string): Promise<any>;
+    stopClientRecording(roomId: string, userId: string): Promise<any>;
     setCloudRecordingReady(roomId: string): Promise<any>;
     /** room session */
     updateRoomSession(params: {
@@ -201,6 +204,17 @@ export declare class FcrCoreServiceApi {
         enable: boolean;
         targetRoles: string[];
     }): Promise<any>;
+    allowClientRecording({ roomId, enable, permissionType, targetRoles, }: {
+        roomId: string;
+        enable: number;
+        permissionType: FcrClientRecordingPermissionType;
+        targetRoles?: string[];
+    }): Promise<any>;
+    allowClientRecordingByUserId({ roomId, toUserUuids, enable, }: {
+        roomId: string;
+        toUserUuids: string[];
+        enable: boolean;
+    }): Promise<any>;
     allowJoinWithPromptSound({ roomId, enable, targetRoles, }: {
         roomId: string;
         enable: boolean;

package/lib/service/api.js

@@ -256,6 +256,24 @@ class FcrCoreServiceApi {
       method: 'PUT'
     });
   }
+  async startClientRecording(roomId, userId) {
+    return this._client.fetch({
+      path: `/v1/rooms/${roomId}/users/${userId}/widgets/clientRecording/1`,
+      method: 'PUT'
+    });
+  }
+  async resumeClientRecording(roomId, userId) {
+    return this._client.fetch({
+      path: `/v1/rooms/${roomId}/users/${userId}/widgets/clientRecording/resume`,
+      method: 'PUT'
+    });
+  }
+  async stopClientRecording(roomId, userId) {
+    return this._client.fetch({
+      path: `/v1/rooms/${roomId}/users/${userId}/widgets/clientRecording/0`,
+      method: 'PUT'
+    });
+  }
   async setCloudRecordingReady(roomId) {
     return this._client.fetch({
       path: `/v1/rooms/${roomId}/records/ready`,
@@ -650,6 +668,36 @@ class FcrCoreServiceApi {
     });
     return res.data;
   }
+  async allowClientRecording({
+    roomId,
+    enable,
+    permissionType,
+    targetRoles
+  }) {
+    const res = await this._client.fetch({
+      path: `/v1/rooms/${roomId}/security/clientRecording/${enable}`,
+      method: 'PUT',
+      data: {
+        targetRoles,
+        selectType: permissionType
+      }
+    });
+    return res.data;
+  }
+  async allowClientRecordingByUserId({
+    roomId,
+    toUserUuids,
+    enable
+  }) {
+    const res = await this._client.fetch({
+      path: `/v1/rooms/${roomId}/security/clientRecording/users/${enable ? 1 : 0}`,
+      method: 'PUT',
+      data: {
+        toUserUuids
+      }
+    });
+    return res.data;
+  }
   async allowJoinWithPromptSound({
     roomId,
     enable,

package/lib/utilities/parameters.js

@@ -33,16 +33,26 @@ const DEFAULT_LOG_FILE_SIZE = 512;
 /** RTC preset parameters configuration mapping table */
 const RTC_PRESET_PARAMS_MAP = {
   [_imports.FcrApplicationPlatform.WINDOWS]: [{
-    'rtc.video.default_hw_decoder_thres': 921600
-  }, {
-    'rtc.video.h264_hw_min_res_level': 4
+    'engine.video.hw_decoder_fallback_config': {
+      max_instances_thres: -1,
+      width_thres: 540,
+      height_thres: 540,
+      decode_time_delay_thres_broadcaster: -1,
+      decode_time_delay_thres_audience: -1
+    }
   }],
   [_imports.FcrApplicationPlatform.MACOS]: [{
     'che.video.screenCaptureMode': 1
   }, {
     'che.video.screen_disable_frame_transparent_check': true
   }, {
-    'rtc.video.h264_hw_min_res_level': 4
+    'engine.video.hw_decoder_fallback_config': {
+      max_instances_thres: -1,
+      width_thres: 540,
+      height_thres: 540,
+      decode_time_delay_thres_broadcaster: -1,
+      decode_time_delay_thres_audience: -1
+    }
   }],
   [_imports.FcrApplicationPlatform.WEB_DESKTOP]: [{
     RESTRICTION_SET_PLAYBACK_DEVICE: false
@@ -101,6 +111,9 @@ const ELECTRON_COMMON_PARAMS = [
   'rtc.video.videoFullrange': 1
 }, {
   'rtc.video.matrixCoefficients': 5
+}, {
+  'rtc.stream_sub_remote_stats': false,
+  'rtc.stream_pub_local_stats': false
 }];
 
 /** ELECTRON platforms set */

package/lib-es/imports.js

@@ -35,6 +35,12 @@ export { Mutex } from 'agora-foundation/lib/worker/mutex';
 
 // Agora RTE exports
 
+export { AgoraRteRecorderState, AgoraRteRecorderReasonCode } from 'agora-rte-sdk';
+
+// Fcr-prefixed re-exports for edu-core layer
+
+export { AgoraRteRecorderState as FcrRecorderState } from 'agora-rte-sdk';
+export { AgoraRteRecorderReasonCode as FcrRecorderReasonCode } from 'agora-rte-sdk';
 export { AgoraRteError } from 'agora-rte-sdk/lib/core/utilities/error';
 export { AgoraError as FcrError } from 'agora-foundation/lib/utilities/error/agora-error';
 export { AgoraRteConnectionState, AgoraRteEngine, convertStreamTypeToPublishState, AgoraRteLatencyLevel, AgoraRteVideoOutputOrientationMode } from 'agora-rte-sdk';

package/lib-es/index.js

@@ -1,5 +1,9 @@
 // types
 
+// Re-export recording types with Fcr prefix
+
+export { FcrRecorderState, FcrRecorderReasonCode } from './imports';
+
 //enums
 export { FcrStreamLatencyLevel, FcrPermissionAction, FcrPrivilegeUserRole, FcrUserRole, FcrStreamState, FcrRegion, FcrStreamType, FcrUserUpdatedReason, FcrRoomConnectorType, FcrVideoSourceType, FcrAudioSourceType, FcrMediaSourceState, FcrVideoRenderMode, FcrVideoStreamType, FcrCapability, FcrAiDenoiseLevel, FcrStreamPrivilegeOperation, FcrStreamPrivilegeVideoSourceType, FcrStreamPrivilegeAudioSourceType, FcrConnectionState, registerPlugin, FcrBoardToolType, FcrBoardShape, FcrVideoEncoderConfig, FcrDualVideoStreamConfig } from './type';
 export { FcrCoreEngineImpl as FcrCoreEngine } from './engine';

package/lib-es/media-control/desktop.js

@@ -28,6 +28,7 @@ import { FcrReturnCode } from '../type';
 import { fcrCapabilitySchema, numberSchema, stringSchema } from '../schema';
 import validateParams from '../utilities/validate-params';
 import { createLogger, generateLogObserver } from '../utilities/logger';
+
 /**
  * @internal
  */

package/lib-es/room-control/helpers/constants.js

@@ -47,6 +47,14 @@ export const ROOM_MESSAGE_COMMANDS = {
   LIVE_STREAMING_UPDATE: 700,
   /** 用户被踢出命令 */
   USER_KICK_OUT: 5,
+  /** 用户widget属性更新命令（widget属性变更的通用cause.cmd） */
+  USER_WIDGET_PROPERTIES_UPDATE: 10,
+  /** 客户端录制权限变更（角色级, cause.cmd=3260） */
+  CLIENT_RECORDING_PERMISSION: 3260,
+  /** 客户端录制状态变更 cause.data.widgetCause.cmd=3261 (通过widget属性下发) */
+  CLIENT_RECORDING_STATE: 3261,
+  /** 用户权限变更（用户级，含客户端录制） */
+  USER_PERMISSION_UPDATE: 3121,
   /** 房间会话请求命令 */
   ROOM_SESSION_REQUEST: 1001,
   /** 房间会话接受命令 */

package/lib-es/room-control/index.js

@@ -19,14 +19,16 @@ import "core-js/modules/es.array.includes.js";
 import "core-js/modules/es.array.push.js";
 import "core-js/modules/es.json.stringify.js";
 import "core-js/modules/esnext.iterator.constructor.js";
+import "core-js/modules/esnext.iterator.find.js";
 import "core-js/modules/esnext.iterator.for-each.js";
+import "core-js/modules/esnext.iterator.some.js";
 function _applyDecs(e, t, r, n, o, a) { function i(e, t, r) { return function (n, o) { return r && r(n), e[t].call(n, o); }; } function c(e, t) { for (var r = 0; r < e.length; r++) e[r].call(t); return t; } function s(e, t, r, n) { if ("function" != typeof e && (n || void 0 !== e)) throw new TypeError(t + " must " + (r || "be") + " a function" + (n ? "" : " or undefined")); return e; } function applyDec(e, t, r, n, o, a, c, u, l, f, p, d, h) { function m(e) { if (!h(e)) throw new TypeError("Attempted to access private element on non-instance"); } var y, v = t[0], g = t[3], b = !u; if (!b) { r || Array.isArray(v) || (v = [v]); var w = {}, S = [], A = 3 === o ? "get" : 4 === o || d ? "set" : "value"; f ? (p || d ? w = { get: _setFunctionName(function () { return g(this); }, n, "get"), set: function (e) { t[4](this, e); } } : w[A] = g, p || _setFunctionName(w[A], n, 2 === o ? "" : A)) : p || (w = Object.getOwnPropertyDescriptor(e, n)); } for (var P = e, j = v.length - 1; j >= 0; j -= r ? 2 : 1) { var D = v[j], E = r ? v[j - 1] : void 0, I = {}, O = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: n, metadata: a, addInitializer: function (e, t) { if (e.v) throw Error("attempted to call addInitializer after decoration was finished"); s(t, "An initializer", "be", !0), c.push(t); }.bind(null, I) }; try { if (b) (y = s(D.call(E, P, O), "class decorators", "return")) && (P = y);else { var k, F; O.static = l, O.private = f, f ? 2 === o ? k = function (e) { return m(e), w.value; } : (o < 4 && (k = i(w, "get", m)), 3 !== o && (F = i(w, "set", m))) : (k = function (e) { return e[n]; }, (o < 2 || 4 === o) && (F = function (e, t) { e[n] = t; })); var N = O.access = { has: f ? h.bind() : function (e) { return n in e; } }; if (k && (N.get = k), F && (N.set = F), P = D.call(E, d ? { get: w.get, set: w.set } : w[A], O), d) { if ("object" == typeof P && P) (y = s(P.get, "accessor.get")) && (w.get = y), (y = s(P.set, "accessor.set")) && (w.set = y), (y = s(P.init, "accessor.init")) && S.push(y);else if (void 0 !== P) throw new TypeError("accessor decorators must return an object with get, set, or init properties or void 0"); } else s(P, (p ? "field" : "method") + " decorators", "return") && (p ? S.push(P) : w[A] = P); } } finally { I.v = !0; } } return (p || d) && u.push(function (e, t) { for (var r = S.length - 1; r >= 0; r--) t = S[r].call(e, t); return t; }), p || b || (f ? d ? u.push(i(w, "get"), i(w, "set")) : u.push(2 === o ? w[A] : i.call.bind(w[A])) : Object.defineProperty(e, n, w)), P; } function u(e, t) { return Object.defineProperty(e, Symbol.metadata || Symbol.for("Symbol.metadata"), { configurable: !0, enumerable: !0, value: t }); } if (arguments.length >= 6) var l = a[Symbol.metadata || Symbol.for("Symbol.metadata")]; var f = Object.create(null == l ? null : l), p = function (e, t, r, n) { var o, a, i = [], s = function (t) { return _checkInRHS(t) === e; }, u = new Map(); function l(e) { e && i.push(c.bind(null, e)); } for (var f = 0; f < t.length; f++) { var p = t[f]; if (Array.isArray(p)) { var d = p[1], h = p[2], m = p.length > 3, y = 16 & d, v = !!(8 & d), g = 0 == (d &= 7), b = h + "/" + v; if (!g && !m) { var w = u.get(b); if (!0 === w || 3 === w && 4 !== d || 4 === w && 3 !== d) throw Error("Attempted to decorate a public method/accessor that has the same name as a previously decorated public method/accessor. This is not currently supported by the decorators plugin. Property name was: " + h); u.set(b, !(d > 2) || d); } applyDec(v ? e : e.prototype, p, y, m ? "#" + h : _toPropertyKey(h), d, n, v ? a = a || [] : o = o || [], i, v, m, g, 1 === d, v && m ? s : r); } } return l(o), l(a), i; }(e, t, o, f); return r.length || u(e, f), { e: p, get c() { var t = []; return r.length && [u(applyDec(e, [r], n, e.name, 5, f, t), f), c.bind(null, t, e)]; } }; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 // Core SDK imports
-import { AgoraObservable, AgoraRteExDataSyncType, jsonstring, to, trace } from '../imports';
+import { AgoraObservable, AgoraRteExDataSyncType, AgoraRteVideoSourceType, jsonstring, to, trace } from '../imports';
 
 // Service and API imports
 
@@ -71,7 +73,7 @@ import { FcrApplicationControlImpl } from './application-control';
  */
 export class FcrBaseRoomControlImpl {
   static {
-    [_initProto] = _applyDecs(this, [[trace, 2, "getSyncTimestamp"], [trace, 2, "getRoomInfo"], [trace, 2, "getRoomSchedule"], [trace, 2, "getLocalExDataSyncTypeList"], [_joinDecs, 2, "join"], [trace, 2, "leave"], [trace, 2, "release"], [trace, 2, "start"], [trace, 2, "end"], [trace, 2, "close"], [trace, 2, "getRoomState"], [trace, 2, "getRoomProperties"], [trace, 2, "getRoomPropertiesByKeyPath"], [_updateRoomPropertiesDecs, 2, "updateRoomProperties"], [_updateIncrementRoomPropertiesDecs, 2, "updateIncrementRoomProperties"], [_deleteRoomPropertiesDecs, 2, "deleteRoomProperties"], [_startCloudRecordingDecs, 2, "startCloudRecording"], [trace, 2, "pauseCloudRecording"], [trace, 2, "resumeCloudRecording"], [trace, 2, "stopCloudRecording"], [trace, 2, "getLiveStreamingState"], [trace, 2, "getLiveStreamingConfig"], [_startLiveStreamingDecs, 2, "startLiveStreaming"], [_updateLiveStreamingLayoutDecs, 2, "updateLiveStreamingLayout"], [trace, 2, "stopLiveStreaming"], [trace, 2, "getCloudRecordingState"], [_sendRoomMessageDecs, 2, "sendRoomMessage"]], []).e;
+    [_initProto] = _applyDecs(this, [[trace, 2, "getSyncTimestamp"], [trace, 2, "getRoomInfo"], [trace, 2, "getRoomSchedule"], [trace, 2, "getLocalExDataSyncTypeList"], [_joinDecs, 2, "join"], [trace, 2, "leave"], [trace, 2, "release"], [trace, 2, "start"], [trace, 2, "end"], [trace, 2, "close"], [trace, 2, "getRoomState"], [trace, 2, "getRoomProperties"], [trace, 2, "getRoomPropertiesByKeyPath"], [_updateRoomPropertiesDecs, 2, "updateRoomProperties"], [_updateIncrementRoomPropertiesDecs, 2, "updateIncrementRoomProperties"], [_deleteRoomPropertiesDecs, 2, "deleteRoomProperties"], [_startCloudRecordingDecs, 2, "startCloudRecording"], [trace, 2, "pauseCloudRecording"], [trace, 2, "resumeCloudRecording"], [trace, 2, "stopCloudRecording"], [trace, 2, "startClientRecording"], [trace, 2, "resumeClientRecording"], [trace, 2, "stopClientRecording"], [trace, 2, "getLiveStreamingState"], [trace, 2, "getLiveStreamingConfig"], [_startLiveStreamingDecs, 2, "startLiveStreaming"], [_updateLiveStreamingLayoutDecs, 2, "updateLiveStreamingLayout"], [trace, 2, "stopLiveStreaming"], [trace, 2, "hasActiveClientRecording"], [trace, 2, "getCloudRecordingState"], [_sendRoomMessageDecs, 2, "sendRoomMessage"]], []).e;
   }
   //@internal
   [(_joinDecs = trace(['options']), _updateRoomPropertiesDecs = trace(['properties', 'cause']), _updateIncrementRoomPropertiesDecs = trace(['increments', 'cause']), _deleteRoomPropertiesDecs = trace(['properties', 'cause']), _startCloudRecordingDecs = trace(['config']), _startLiveStreamingDecs = trace(['data']), _updateLiveStreamingLayoutDecs = trace(['layoutType']), _sendRoomMessageDecs = trace(['payload', 'guaranteedDelivery']), "logger")] = (_initProto(this), createLogger({
@@ -81,6 +83,8 @@ export class FcrBaseRoomControlImpl {
   _joinRoomSuccess = false;
   _joining = false;
   _joinState = ROOM_CONTROL_CONSTANTS.JOIN_STATE.CANCELED;
+  _isClientRecordingOwner = false;
+  _isStartingClientRecording = false;
   constructor(_engine, _scene, _api, _config, _roomType, _chatConnection, _sharedCache, _chatRoomControl) {
     this._engine = _engine;
     this._scene = _scene;
@@ -229,8 +233,45 @@ export class FcrBaseRoomControlImpl {
           this._joinState = ROOM_CONTROL_CONSTANTS.JOIN_STATE.CANCELED;
           this._cleanup();
         }
+        // Handle user-level local recording permission change (cmd=3121)
+        if (event.cause?.cmd === ROOM_MESSAGE_COMMANDS.USER_PERMISSION_UPDATE && event.modifiedUser.userId === this._scene.localUser.getLocalUserId()) {
+          const causeData = event.cause?.data;
+          if (causeData?.removePermissions?.includes('record:startClientRecording')) {
+            if (this.isLocalClientRecordingActive()) {
+              this.stopClientRecording().catch(e => {
+                this.logger.error(`auto-stop client recording failed: ${e.message}`);
+              });
+            }
+          }
+        }
+      }
+    };
+
+    // 初始化客户端录制观察者
+    this._clientRecordingObserver = {
+      onRecorderStateChanged: (_channelId, _uid, state, reason) => {
+        this.logger.info(`onRecorderStateChanged: state=${state}, reason=${reason}, sceneId=${this._scene.sceneId}`);
+        this._observable.notifyObservers('onClientRecordingStateChanged', this._scene.sceneId, state, reason);
       }
     };
+
+    // 客户端录制观察者由子类（FcrMainRoomControlImpl）注册，基类不注册
+  }
+
+  /**
+   * 注册客户端录制观察者。由主房间子类在构造时调用。
+   */
+  _registerClientRecordingObserver() {
+    this._engine.getMediaControl().addClientRecordingObserver(this._clientRecordingObserver);
+    this._isClientRecordingOwner = true;
+  }
+
+  /**
+   * 移除客户端录制观察者。由 _cleanup 调用时需要判断是否已注册。
+   */
+  _unregisterClientRecordingObserver() {
+    this._engine.getMediaControl().removeClientRecordingObserver(this._clientRecordingObserver);
+    this._isClientRecordingOwner = false;
   }
 
   /**
@@ -577,6 +618,89 @@ export class FcrBaseRoomControlImpl {
     await handleRequestError(() => this._api.stopCloudRecording(this._scene.sceneId), ErrorModuleCode.FCR_ROOM, 'stop cloud recording failed');
     return FcrReturnCode.SUCCESS;
   }
+  async startClientRecording(config) {
+    // 防止并发调用
+    if (this._isStartingClientRecording) {
+      this.logger.warn('startClientRecording: already starting, ignoring duplicate call');
+      return FcrReturnCode.SUCCESS;
+    }
+    const localUserId = this._scene.localUser.getLocalUserId();
+
+    // 标记正在启动本地录制，避免在 API 调用后、SDK 录制开始前的时间窗口内触发错误的提示
+    this._isStartingClientRecording = true;
+    let serverRecordingStarted = false;
+    try {
+      await handleRequestError(() => this._api.startClientRecording(this._scene.sceneId, localUserId), ErrorModuleCode.FCR_ROOM, 'start client recording failed');
+      serverRecordingStarted = true;
+
+      // 使用 mediaControl 来启动本地录制
+      const mediaControl = this._engine.getMediaControl();
+      const isScreenShareActive = mediaControl.isScreenShareActive();
+      const currentScreenShareSourceId = mediaControl.getCurrentScreenShareSourceId();
+
+      // 获取本地用户的主流 streamId 作为录制 uid（streamId 是数字，userUuid 可能是十六进制字符串）
+      const localStreams = this._scene.getStreamsByUserId(localUserId);
+      const mainStream = localStreams.find(s => s.videoSourceType === AgoraRteVideoSourceType.CAMERA) || localStreams[0];
+      if (!mainStream) {
+        throw new Error(`No stream found for local user: ${localUserId}`);
+      }
+      const uid = Number(mainStream.streamId);
+      await mediaControl.startClientRecording(this._scene.sceneId, uid, config, isScreenShareActive, currentScreenShareSourceId);
+      return FcrReturnCode.SUCCESS;
+    } catch (e) {
+      // API 调用成功但 SDK 启动失败时，回滚服务端状态
+      if (serverRecordingStarted) {
+        this.logger.error(`startClientRecording SDK failed, rolling back server state: ${e.message}`);
+        this._api.stopClientRecording(this._scene.sceneId, localUserId).catch(rollbackErr => {
+          this.logger.error(`startClientRecording rollback failed: ${rollbackErr.message}`);
+        });
+      }
+      throw e;
+    } finally {
+      this._isStartingClientRecording = false;
+    }
+  }
+  async resumeClientRecording() {
+    const localUserId = this._scene.localUser.getLocalUserId();
+    await handleRequestError(() => this._api.resumeClientRecording(this._scene.sceneId, localUserId), ErrorModuleCode.FCR_ROOM, 'resume client recording failed');
+    return FcrReturnCode.SUCCESS;
+  }
+  async stopClientRecording() {
+    const localUserId = this._scene.localUser.getLocalUserId();
+
+    // Step 1: 使用 mediaControl 的 stopClientRecording（即使失败也继续通知服务端）
+    const mediaControl = this._engine.getMediaControl();
+    try {
+      await mediaControl.stopClientRecording();
+    } catch (e) {
+      this.logger.error(`mediaControl.stopClientRecording failed: ${e.message}`);
+    }
+
+    // Step 2: 无论 SDK 停止是否成功，都通知服务器停止录制
+    await handleRequestError(() => this._api.stopClientRecording(this._scene.sceneId, localUserId), ErrorModuleCode.FCR_ROOM, 'stop client recording failed');
+    return FcrReturnCode.SUCCESS;
+  }
+  isLocalClientRecordingActive() {
+    // 如果正在启动本地录制，也返回 true，避免在启动过程中触发错误的"其他人开启录制"提示
+    const mediaControl = this._engine.getMediaControl();
+    return this._isStartingClientRecording || mediaControl.isClientRecordingActive();
+  }
+  isClientRecordingOwnsCapture() {
+    const mediaControl = this._engine.getMediaControl();
+    return mediaControl.isClientRecordingOwnsCapture();
+  }
+  async resumeClientRecordingOwnCapture() {
+    const mediaControl = this._engine.getMediaControl();
+    await mediaControl.resumeClientRecordingOwnCapture();
+  }
+  async waitForScreenCaptureStopped() {
+    const mediaControl = this._engine.getMediaControl();
+    await mediaControl.waitForScreenCaptureStopped();
+  }
+  releaseClientRecordingOwnCapture() {
+    const mediaControl = this._engine.getMediaControl();
+    mediaControl.releaseClientRecordingOwnCapture();
+  }
   getLiveStreamingState() {
     let liveStreamingState = this._scene.getScenePropertiesByKeyPath('live.state');
     if (liveStreamingState === LIVE_STREAMING_STATE_VALUES.STARTED) {
@@ -616,6 +740,11 @@ export class FcrBaseRoomControlImpl {
     await this._liveStreamingAction(() => this._api.stopLiveStreaming(this._scene.sceneId), 'stop live streaming failed');
     return FcrReturnCode.SUCCESS;
   }
+  hasActiveClientRecording() {
+    const userControl = this.getUserControl();
+    const users = userControl.getUserList();
+    return users.some(user => userControl.getUserClientRecordingState(user.userId));
+  }
   getCloudRecordingState() {
     const {
       state,
@@ -644,6 +773,21 @@ export class FcrBaseRoomControlImpl {
   async _cleanup() {
     this._scene.removeObserver(this._sceneObserver);
     this._engine.removeObserver(this._engineObserver);
+
+    // 只有注册过录制观察者的 room control 才拥有录制生命周期，
+    // 其他房间（如等候室）的 cleanup 不应停止共享 mediaControl 上的录制。
+    if (this._isClientRecordingOwner) {
+      this._unregisterClientRecordingObserver();
+      try {
+        const mediaControl = this._engine.getMediaControl();
+        if (mediaControl.isClientRecordingActive()) {
+          await mediaControl.stopClientRecording();
+          this.logger.info('_cleanup: stopped client recording');
+        }
+      } catch (e) {
+        this.logger.error(`_cleanup: failed to stop client recording: ${e.message}`);
+      }
+    }
     this._sharedCache.getRoomCache(this._scene.sceneId).clear();
     try {
       return await Promise.all([this._chatRoomControl?.leave(), this.sharingControl?.getBoardControl().close(), this.sharingControl?.getAnnotationControl().close(), this._scene.leave()]);