@xmaxai/web-sdk 1.0.5 → 1.0.7

package/dist/{chunk-VMJXIVUF.js → chunk-4O5BSMUX.js}

@@ -205,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.5";
+var XMAX_SDK_VERSION = "1.0.7";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -600,7 +600,6 @@ var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
 var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   RealtimeModel2["x2_0"] = "x2.0";
   RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
-  RealtimeModel2["x2_0_agora"] = "x2.0-agora";
   RealtimeModel2["x2_1_preview"] = "x2.1-preview";
   return RealtimeModel2;
 })(RealtimeModel || {});
@@ -616,12 +615,10 @@ function modelDefaults(model) {
 var MODEL_DISPLAY_NAMES = {
   ["x2.0" /* x2_0 */]: "X2.0",
   ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
-  ["x2.0-agora" /* x2_0_agora */]: "X2.1-preview-agora",
-  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-vertc"
+  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora"
 };
 var MODEL_BASE_URLS = {
-  ["x2.0-agora" /* x2_0_agora */]: "https://dev.xmaxai.com/open/api/v1",
-  ["x2.1-preview" /* x2_1_preview */]: "https://dev.xmaxai.com/open/api/v1"
+  ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1"
 };
 var RESOLUTION_BUCKETS = {
   ["x2.0" /* x2_0 */]: [],
@@ -629,10 +626,6 @@ var RESOLUTION_BUCKETS = {
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ],
-  ["x2.0-agora" /* x2_0_agora */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
   ["x2.1-preview" /* x2_1_preview */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
@@ -641,7 +634,6 @@ var RESOLUTION_BUCKETS = {
 var MAXIMUM_INPUT_PIXELS = {
   ["x2.0" /* x2_0 */]: 128e4,
   ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
-  ["x2.0-agora" /* x2_0_agora */]: 21e5,
   ["x2.1-preview" /* x2_1_preview */]: 21e5
 };
 function modelDisplayName(model) {
@@ -674,8 +666,7 @@ function defaultCameraVideoFormat(model) {
 var MODEL_RTC_PROVIDERS = {
   ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
   ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
-  ["x2.0-agora" /* x2_0_agora */]: Object.freeze(["agora" /* agora */]),
-  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["vertc" /* vertc */])
+  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */])
 };
 function supportedRtcProviders(model) {
   return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
@@ -1269,6 +1260,11 @@ ${JSON.stringify({
       receivedBytes: valid(rtc.RecvBytes),
       localVideo,
       remoteVideo: remote,
+      capture: {
+        width: valid(local.captureResolutionWidth, 1),
+        height: valid(local.captureResolutionHeight, 1),
+        frameRate: valid(local.captureFrameRate)
+      },
       localAudio: client.getLocalAudioStats(),
       remoteAudio: client.getRemoteAudioStats()
     }, null, 2)}`, 2 /* performance */);
@@ -1316,6 +1312,231 @@ function rtcOrientedVideoSize(size, environment) {
   return shouldTransposeRtcVideoSize(environment) ? { width: size.height, height: size.width } : size;
 }
 
+// src/Foundation/RTC/Agora/AgoraVideoSender.ts
+var AgoraVideoSender = class {
+  static async apply(track, config, ensureActive2) {
+    ensureActive2();
+    const sender = track.getRTCRtpTransceiver()?.sender;
+    if (!sender) throw new XmaxError("RTC_ERROR" /* rtcError */, "WebRTC video sender is unavailable");
+    const capture = sender.track?.getSettings();
+    if (!capture?.width || !capture.height) {
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "WebRTC capture dimensions are unavailable");
+    }
+    const scale = Math.max(1, capture.width / config.width, capture.height / config.height);
+    const parameters = sender.getParameters();
+    if (parameters.encodings?.length !== 1) {
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "Sender-only configuration requires one video encoding");
+    }
+    const encoding = parameters.encodings[0];
+    const previous = { ...encoding };
+    const previousPreference = parameters.degradationPreference;
+    encoding.scaleResolutionDownBy = scale;
+    encoding.maxFramerate = config.frameRate;
+    encoding.maxBitrate = Math.round(config.maximumBitrate * 1e3);
+    parameters.degradationPreference = config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "maintain-framerate" : "maintain-resolution";
+    await sender.setParameters(parameters);
+    ensureActive2();
+    if (track.getRTCRtpTransceiver()?.sender !== sender) {
+      throw new XmaxError("CANCELLED" /* cancelled */, "WebRTC video sender changed during configuration");
+    }
+    const applied = sender.getParameters();
+    const actual = applied.encodings?.[0];
+    if (!actual || Math.abs((actual.scaleResolutionDownBy ?? 1) - scale) > 1e-4 || actual.maxFramerate !== encoding.maxFramerate || actual.maxBitrate !== encoding.maxBitrate) {
+      if (actual && applied.encodings.length === 1) {
+        for (const key of ["scaleResolutionDownBy", "maxFramerate", "maxBitrate"]) {
+          if (previous[key] === void 0) delete actual[key];
+          else actual[key] = previous[key];
+        }
+        if (previousPreference === void 0) delete applied.degradationPreference;
+        else applied.degradationPreference = previousPreference;
+        await sender.setParameters(applied);
+      }
+      throw new XmaxError("RTC_ERROR" /* rtcError */, "Browser did not retain WebRTC video sender parameters");
+    }
+    XmaxLogger.rtc.info(() => `Agora \u53D1\u9001\u53C2\u6570\u5B9E\u9A8C (Agora Sender Parameters)
+${JSON.stringify({
+      capture: { width: capture.width, height: capture.height, frameRate: capture.frameRate },
+      target: { width: config.width, height: config.height, frameRate: config.frameRate },
+      scaleResolutionDownBy: actual.scaleResolutionDownBy,
+      maxFramerate: actual.maxFramerate,
+      maxBitrateKbps: actual.maxBitrate / 1e3,
+      minimumBitrateApplied: false
+    }, null, 2)}`, 2 /* performance */);
+  }
+};
+
+// src/Foundation/Media/Camera/CameraRotation.ts
+function validateCameraRotation(rotation) {
+  if (![0, 90, 180, 270].includes(rotation)) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation must be 0, 90, 180 or 270");
+  }
+}
+
+// src/Foundation/Media/Camera/CameraRotationProcessor.ts
+var CameraRotationProcessor = class {
+  constructor(options) {
+    __publicField(this, "options", options);
+    __publicField(this, "video", document.createElement("video"));
+    __publicField(this, "canvas", document.createElement("canvas"));
+    __publicField(this, "context");
+    __publicField(this, "stream");
+    __publicField(this, "source");
+    __publicField(this, "frameCallback");
+    __publicField(this, "timer");
+    __publicField(this, "cancelPending");
+    __publicField(this, "stopped", false);
+    __publicField(this, "version", 0);
+    __publicField(this, "sourceEnded", () => {
+      this.fail(new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera source ended during rotation"));
+    });
+    this.canvas.width = options.width;
+    this.canvas.height = options.height;
+    const context = this.canvas.getContext("2d", { alpha: false });
+    if (!context || typeof this.canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas camera rotation is not supported by this browser");
+    }
+    this.context = context;
+    this.video.muted = true;
+    this.video.autoplay = true;
+    this.video.playsInline = true;
+  }
+  /** 等待第一帧实际绘制成功；换摄像头时复用输出轨，不重建 sender。 */
+  async setSource(source) {
+    if (this.stopped) throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation has stopped");
+    if (source.readyState === "ended") {
+      this.stop();
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera rotation requires a live source");
+    }
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    const version = ++this.version;
+    this.source = source;
+    source.addEventListener("ended", this.sourceEnded);
+    this.video.srcObject = new MediaStream([source]);
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          this.cancelPending = void 0;
+          if (error) reject(error);
+          else resolve();
+        };
+        const timeout = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Timed out waiting for a camera rotation frame")), 1e4);
+        this.cancelPending = () => finish(new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed"));
+        void this.video.play().then(() => {
+          if (settled || this.stopped || version !== this.version) return;
+          const firstFrame = () => {
+            if (settled || this.stopped || version !== this.version) return;
+            try {
+              if (!this.draw()) {
+                this.schedule(firstFrame);
+                return;
+              }
+              this.stream ?? (this.stream = this.canvas.captureStream(this.options.frameRate));
+              if (!this.stream.getVideoTracks()[0]) throw new Error("Canvas did not produce a video track");
+              this.requestFrame();
+              finish();
+              this.schedule(() => this.render(version));
+            } catch (error) {
+              finish(error);
+            }
+          };
+          this.schedule(firstFrame);
+        }, finish);
+      });
+      if (this.stopped || version !== this.version) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed");
+      }
+      return this.stream.getVideoTracks()[0];
+    } catch (error) {
+      if (version === this.version) this.stop();
+      throw XmaxError.from(error);
+    }
+  }
+  /** 换设备前解除旧原始轨监听，保留 Canvas 最后一帧及输出轨。 */
+  pauseSource() {
+    ++this.version;
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    ++this.version;
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+    this.stream?.getTracks().forEach((track) => track.stop());
+    this.stream = void 0;
+    this.canvas.width = this.canvas.height = 0;
+  }
+  draw() {
+    const { videoWidth: width, videoHeight: height } = this.video;
+    if (this.video.readyState < 2 || !width || !height) return false;
+    const { width: outWidth, height: outHeight, rotation } = this.options;
+    const quarterTurn = rotation === 90 || rotation === 270;
+    const targetWidth = quarterTurn ? outHeight : outWidth;
+    const targetHeight = quarterTurn ? outWidth : outHeight;
+    const scale = Math.max(targetWidth / width, targetHeight / height);
+    const cropWidth = targetWidth / scale, cropHeight = targetHeight / scale;
+    this.context.setTransform(1, 0, 0, 1, outWidth / 2, outHeight / 2);
+    this.context.rotate(rotation * Math.PI / 180);
+    this.context.drawImage(
+      this.video,
+      (width - cropWidth) / 2,
+      (height - cropHeight) / 2,
+      cropWidth,
+      cropHeight,
+      -targetWidth / 2,
+      -targetHeight / 2,
+      targetWidth,
+      targetHeight
+    );
+    return true;
+  }
+  render(version) {
+    if (this.stopped || version !== this.version) return;
+    try {
+      if (this.draw()) this.requestFrame();
+      this.schedule(() => this.render(version));
+    } catch (error) {
+      this.fail(XmaxError.from(error));
+    }
+  }
+  requestFrame() {
+    const track = this.stream?.getVideoTracks()[0];
+    track?.requestFrame?.();
+  }
+  schedule(callback) {
+    if (typeof this.video.requestVideoFrameCallback === "function") {
+      this.frameCallback = this.video.requestVideoFrameCallback(callback);
+    } else {
+      this.timer = setTimeout(callback, 1e3 / this.options.frameRate);
+    }
+  }
+  cancelFrame() {
+    if (this.frameCallback !== void 0) this.video.cancelVideoFrameCallback(this.frameCallback);
+    clearTimeout(this.timer);
+    this.frameCallback = void 0;
+    this.timer = void 0;
+  }
+  fail(error) {
+    this.stop();
+    this.options.onError(error);
+  }
+};
+
 // src/Foundation/RTC/Agora/AgoraRtcManager.ts
 var _AgoraRtcManager = class _AgoraRtcManager {
   /**
@@ -1332,9 +1553,16 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __publicField(this, "initialization");
     __publicField(this, "lifecycle", 0);
     __publicField(this, "camera");
+    __publicField(this, "cameraSource");
+    __publicField(this, "cameraRotation");
+    __publicField(this, "captureVersion", 0);
     __publicField(this, "microphone");
     __publicField(this, "externalVideo");
     __publicField(this, "externalAudio");
+    __publicField(this, "appliedOptimizationModes", /* @__PURE__ */ new WeakMap());
+    __publicField(this, "cameraSenderConfiguration");
+    __publicField(this, "senderUpdateTail", Promise.resolve());
+    __publicField(this, "cameraTransceiverListener");
     __publicField(this, "connection");
     __publicField(this, "roomVersion", 0);
     /**
@@ -1351,6 +1579,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
      */
     __publicField(this, "listener");
     __publicField(this, "statisticsTimer");
+    __publicField(this, "networkQualitySuspended", false);
     __publicField(this, "audioVolumes", /* @__PURE__ */ new Map());
     __publicField(this, "requestedAudio", /* @__PURE__ */ new Set());
     /**
@@ -1420,7 +1649,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     this.clearRoom();
     this.client = void 0;
     client?.removeAllListeners();
-    this.camera?.close();
+    this.releaseCameraCapture();
     this.microphone?.close();
     this.externalVideo?.close();
     this.externalAudio?.close();
@@ -1444,22 +1673,55 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async startCameraCapture(options) {
     const client = this.requireClient();
-    if (this.camera || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "A local video source is already active");
     }
+    const rotation = options.rotation ?? 0;
+    validateCameraRotation(rotation);
+    const version = ++this.captureVersion;
+    let source;
     try {
-      const captureSize = rtcOrientedVideoSize(options);
-      const camera = await this.sdk.createCameraVideoTrack({
+      const captureSize = rtcOrientedVideoSize(rotation === 90 || rotation === 270 ? { width: options.height, height: options.width } : options);
+      source = await this.sdk.createCameraVideoTrack({
         facingMode: options.position === "front" /* front */ ? "user" : "environment",
         encoderConfig: { width: captureSize.width, height: captureSize.height, frameRate: options.frameRate }
       });
-      if (this.client !== client) {
-        camera.close();
+      if (this.client !== client || version !== this.captureVersion) {
+        source.close();
         throw this.cancelled();
       }
+      this.cameraSource = source;
+      let camera = source;
+      if (rotation !== 0) {
+        const processor = new CameraRotationProcessor({
+          ...options,
+          rotation,
+          onError: (error) => this.listener?.onError?.(error)
+        });
+        this.cameraRotation = processor;
+        const output = await processor.setSource(source.getMediaStreamTrack());
+        if (this.client !== client || version !== this.captureVersion) throw this.cancelled();
+        camera = this.sdk.createCustomVideoTrack({
+          mediaStreamTrack: output,
+          width: options.width,
+          height: options.height,
+          frameRate: options.frameRate
+        });
+      }
       this.camera = camera;
+      this.cameraTransceiverListener = () => {
+        if (this.client === client && client.localTracks.includes(camera) && this.videoPublishRequested && !this.rejoinTask) {
+          void this.restoreCameraSender(camera).catch(() => {
+            if (this.camera === camera && this.videoPublishRequested) {
+              XmaxLogger.rtc.warning(() => "Agora \u53D1\u9001\u53C2\u6570\u6062\u590D\u5931\u8D25 (Agora Sender Parameters Restore Failed)");
+            }
+          });
+        }
+      };
+      camera.on("transceiver-updated", this.cameraTransceiverListener);
       return camera.getMediaStreamTrack();
     } catch (error) {
+      if (version === this.captureVersion) this.releaseCameraCapture();
       throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
     }
   }
@@ -1467,25 +1729,50 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 切换声网相机设备并返回切换后的原生轨道。
    */
   async switchCameraCapture(to) {
-    const camera = this.requireCamera();
-    await this.run(() => camera.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
-    if (this.camera !== camera) throw this.cancelled();
+    const source = this.requireCamera();
+    const camera = this.camera;
+    this.cameraRotation?.pauseSource();
+    try {
+      await this.run(() => source.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
+    } catch (error) {
+      if (this.camera === camera && this.cameraRotation) {
+        await this.cameraRotation.setSource(source.getMediaStreamTrack()).catch((restoreError) => {
+          this.listener?.onError?.(XmaxError.from(restoreError));
+        });
+      }
+      throw error;
+    }
+    if (this.camera !== camera || this.cameraSource !== source) throw this.cancelled();
+    if (this.cameraRotation) {
+      await this.cameraRotation.setSource(source.getMediaStreamTrack());
+      if (this.camera !== camera) throw this.cancelled();
+    }
+    if (this.videoPublishRequested) await this.restoreCameraSender(camera);
     return camera.getMediaStreamTrack();
   }
   /**
    * 停止采集并释放摄像头。
    */
   async stopCameraCapture() {
+    this.releaseCameraCapture();
+  }
+  releaseCameraCapture() {
+    ++this.captureVersion;
     const camera = this.camera;
+    this.releaseCameraSender();
     this.camera = void 0;
     camera?.close();
+    this.cameraRotation?.stop();
+    this.cameraRotation = void 0;
+    if (this.cameraSource !== camera) this.cameraSource?.close();
+    this.cameraSource = void 0;
   }
   /**
    * 将外部原生轨包装为 Agora 本地轨，不申请设备权限；失败时释放本次克隆。
    */
   async setExternalMediaTracks(tracks) {
     this.requireClient();
-    if (this.camera || this.microphone || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.microphone || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
     }
     if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
@@ -1512,11 +1799,26 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     }
   }
   /**
-   * 应用公共编码配置；仅相机源补偿移动端转置，Canvas 外部源使用原始方向。
+   * 摄像头实验走原生 sender（发布前暂存）；外部视频仍走 Agora 编码配置。
    */
   async configureVideoEncoding(config) {
     const camera = this.requireLocalVideo();
-    const encodingSize = this.externalVideo ? config : rtcOrientedVideoSize(config);
+    if (camera === this.camera) {
+      const client = this.requireClient(), version = this.roomVersion;
+      const published = this.videoPublishRequested;
+      await this.run(() => this.queueSenderUpdate(async () => {
+        const ensureActive2 = () => {
+          if (this.camera !== camera || this.client !== client || this.roomVersion !== version || published && !this.videoPublishRequested) throw this.cancelled();
+        };
+        ensureActive2();
+        if (this.videoPublishRequested) {
+          await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
+        }
+        this.cameraSenderConfiguration = { ...config };
+      }));
+      return;
+    }
+    const encodingSize = config;
     await this.run(async () => {
       await camera.setEncoderConfiguration({
         width: encodingSize.width,
@@ -1525,8 +1827,39 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         bitrateMin: config.minimumBitrate,
         bitrateMax: config.maximumBitrate
       });
-      await camera.setOptimizationMode(config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail");
+      if (this.appliedOptimizationModes.get(camera) !== config.encoderPreference) {
+        await camera.setOptimizationMode(config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail");
+        this.appliedOptimizationModes.set(camera, config.encoderPreference);
+      }
+    });
+  }
+  queueSenderUpdate(operation) {
+    const next = this.senderUpdateTail.then(operation);
+    this.senderUpdateTail = next.catch(() => {
     });
+    return next;
+  }
+  /** 发布/重建 sender 后恢复最近成功的目标配置；排队时不捕获过期的参数对象。 */
+  restoreCameraSender(camera) {
+    const client = this.client, version = this.roomVersion;
+    return this.queueSenderUpdate(async () => {
+      const ensureActive2 = () => {
+        if (this.camera !== camera || this.client !== client || this.roomVersion !== version || !this.videoPublishRequested) {
+          throw this.cancelled();
+        }
+      };
+      ensureActive2();
+      const config = this.cameraSenderConfiguration;
+      if (config) await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
+    });
+  }
+  cameraEncodingConfiguration(config) {
+    return this.cameraRotation ? config : { ...config, ...rtcOrientedVideoSize(config) };
+  }
+  releaseCameraSender() {
+    if (this.cameraTransceiverListener) this.camera?.off("transceiver-updated", this.cameraTransceiverListener);
+    this.cameraTransceiverListener = void 0;
+    this.cameraSenderConfiguration = void 0;
   }
   /**
    * 使用会话下发的字符串频道与 UID 入房；不采信后端区域覆盖。
@@ -1645,6 +1978,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (this.videoPublishRequested && video) {
       await this.run(() => client.publish(video));
       this.ensureRoomCurrent(client, version);
+      if (video === this.camera) await this.restoreCameraSender(this.camera);
     }
     if (this.audioPublishRequested && audio) {
       await this.run(() => client.publish(audio));
@@ -1674,6 +2008,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (client !== this.client || !this.videoPublishRequested) throw this.cancelled();
     if (client.localTracks.includes(camera)) return;
     await this.run(() => client.publish(camera));
+    if (camera === this.camera) await this.run(() => this.restoreCameraSender(this.camera));
   }
   /**
    * 停止视频发布但保留采集与预览。
@@ -1871,6 +2206,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const handleExpired = () => {
       if (!active() || this.tokenExpired) return;
       this.tokenExpired = true;
+      this.listener?.onNetworkStatistics?.(void 0);
       this.listener?.onTokenExpired?.();
     };
     client.on("user-published", (user, kind) => {
@@ -1894,13 +2230,15 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       if (mediaActive()) this.listener?.onCustomMessageReceived(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data));
     });
     client.on("network-quality", (quality) => {
-      if (mediaActive()) AgoraRtcStatistics.network(quality, this.listener);
+      if (mediaActive() && !this.networkQualitySuspended) AgoraRtcStatistics.network(quality, this.listener);
     });
     client.on("token-privilege-will-expire", () => {
       if (active() && !this.tokenExpired) this.listener?.onTokenWillExpire?.();
     });
     client.on("token-privilege-did-expire", handleExpired);
     client.on("connection-state-change", (state2, previous, reason) => {
+      if (this.client === client) this.networkQualitySuspended = state2 !== "CONNECTED";
+      if (active() && state2 !== "CONNECTED") this.listener?.onNetworkStatistics?.(void 0);
       if (state2 === "DISCONNECTED" && reason === "TOKEN_EXPIRE") {
         handleExpired();
         return;
@@ -1918,6 +2256,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     this.cancelRejoin?.();
     this.connection = void 0;
     this.tokenExpired = false;
+    this.networkQualitySuspended = false;
     this.videoPublishRequested = false;
     this.audioPublishRequested = false;
     clearInterval(this.statisticsTimer);
@@ -1953,8 +2292,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 获取已启动的相机采集。
    */
   requireCamera() {
-    if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
-    return this.camera;
+    if (!this.cameraSource || !this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
+    return this.cameraSource;
   }
   /**
    * 获取当前可编码、发布的视频轨，不要求来源为摄像头。
@@ -2393,6 +2732,9 @@ var TrtcRtcManager = class {
    * @throws 引擎未初始化、已在采集、设备不可用或权限被拒绝时抛出错误。
    */
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.isCapturing || this.externalVideo) {
       throw new XmaxError(
@@ -3039,6 +3381,9 @@ var VeRtcManager = class {
     }
   }
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.camera || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is already prepared");
@@ -3875,6 +4220,7 @@ var _CameraController = class _CameraController {
    *
    * @param options.videoFormat 期望的输出尺寸、帧率和编码配置；尺寸按模型规则调整。
    * @param options.position 首次启动时使用的摄像头位置。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @param options.useMicrophone 是否申请麦克风权限并允许实时连接时启动音频采集。
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
    * @returns 包含本地相机视频轨道的媒体流。
@@ -3887,6 +4233,7 @@ var _CameraController = class _CameraController {
         "Stop the current local camera stream before creating another one"
       );
     }
+    validateCameraRotation(options.rotation ?? 0);
     const resolvedFormat = this.resolveVideoFormat(options.videoFormat);
     const track = new RealtimeVideoTrack({
       id: _CameraController.localVideoTrackID,
@@ -3909,7 +4256,8 @@ var _CameraController = class _CameraController {
         width: resolvedFormat.width,
         height: resolvedFormat.height,
         frameRate: resolvedFormat.fps,
-        position: options.position
+        position: options.position,
+        ...options.rotation !== void 0 ? { rotation: options.rotation } : {}
       });
       track.mediaStreamTrack = mediaTrack;
       this.previewStream = new MediaStream([mediaTrack]);
@@ -5043,6 +5391,7 @@ var RoomEvent = class _RoomEvent {
       event: "start",
       params: {
         ..._RoomEvent.generationParameters(options),
+        mirror: options.mirror ?? false,
         ...options.context.referenceVideo && {
           ref_video_path: options.context.referenceVideo.path,
           sample_method: options.context.referenceVideo.sampleMethod,
@@ -5495,6 +5844,7 @@ var RoomController = class {
   startGeneration(options) {
     return this.send(
       RoomEvent.start({
+        mirror: options.mirror ?? false,
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
@@ -5646,6 +5996,7 @@ var _EncodingController = class _EncodingController {
      * 基础层组件
      */
     __publicField(this, "rtcManager");
+    __publicField(this, "lastAppliedConfiguration");
     this.rtcManager = options.rtcManager;
   }
   /**
@@ -5681,14 +6032,38 @@ var _EncodingController = class _EncodingController {
         "Minimum bitrate must not exceed maximum bitrate after applying SDK defaults"
       );
     }
-    await this.rtcManager.configureVideoEncoding({
+    const configuration = {
       width: videoFormat.width,
       height: videoFormat.height,
       frameRate: videoFormat.fps,
       minimumBitrate: minimum,
       maximumBitrate: maximum,
       encoderPreference: ENCODER_PREFERENCE_MAP[videoFormat.encoderPreference]
+    };
+    await this.rtcManager.configureVideoEncoding(configuration);
+    this.lastAppliedConfiguration = { ...configuration };
+  }
+  /** 只替换目标帧率，保留最近成功应用的尺寸、已解析码率区间和偏好。 */
+  async updateFrameRate(fps) {
+    const previous = this.lastAppliedConfiguration;
+    if (!previous) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Apply an encoder configuration before updating frame rate");
+    }
+    const format = new RealtimeVideoFormat({
+      width: previous.width,
+      height: previous.height,
+      fps,
+      minimumBitrate: previous.minimumBitrate,
+      maximumBitrate: previous.maximumBitrate,
+      encoderPreference: previous.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "maintainFramerate" /* maintainFramerate */ : "maintainQuality" /* maintainQuality */
     });
+    format.validate();
+    if (fps !== previous.frameRate) {
+      const next = { ...previous, frameRate: fps };
+      await this.rtcManager.configureVideoEncoding(next);
+      this.lastAppliedConfiguration = next;
+    }
+    return format;
   }
   /**
    * 按像素面积与帧率计算码率区间（kbps）：流畅优先为最低，画质优先为最高。
@@ -5926,9 +6301,13 @@ var StreamController = class {
    *
    * @throws 格式无效、码率区间无效或 RTC 配置失败时抛出错误。
    */
-  async setVideoEncoderConfig(videoFormat) {
+  async updateUplinkVideoFormat(videoFormat) {
     await this.encodingController.configure(videoFormat);
   }
+  /** 不根据新帧率重新推算码率区间。 */
+  async updateUplinkFrameRate(fps) {
+    return this.encodingController.updateFrameRate(fps);
+  }
   /**
    * 加入 RTC 房间并发布本地媒体流。
    *
@@ -6014,6 +6393,7 @@ var StreamController = class {
     try {
       const sending = this.roomController.startGeneration({
         taskID,
+        mirror: options.mirror ?? false,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
@@ -6087,7 +6467,7 @@ var StreamController = class {
    *
    * @throws 操作已取消、房间未就绪或信令发送失败时抛出错误。
    */
-  async changeTargetSize(taskID, targetSize, ensureActive2) {
+  async updateDownlinkVideoResolution(taskID, targetSize, ensureActive2) {
     try {
       await this.roomController.changeTargetSize({ taskID, targetSize, ensureActive: ensureActive2 });
     } catch (error) {
@@ -6509,6 +6889,195 @@ var StreamController = class {
   }
 };
 
+// src/Stream/Quality/QualityTiers.ts
+var INITIAL_QUALITY_LEVEL = 2;
+var QUALITY_TIERS = {
+  L1: { width: 1024, height: 1920, frameRate: 30 },
+  L2: { width: 768, height: 1440, frameRate: 24 },
+  L3: { width: 640, height: 1200, frameRate: 24 },
+  L4: { width: 512, height: 960, frameRate: 20 },
+  L5: { width: 384, height: 720, frameRate: 16 }
+};
+
+// src/Stream/Quality/QualityPolicy.ts
+var DEFAULT_POLICY = {
+  poorSamples: 3,
+  goodSamples: 5,
+  stabilizationMs: 4e3,
+  probeMs: 2e4,
+  upgradeCooldownMs: 6e4,
+  sampleTimeoutMs: 5e3
+};
+
+// src/Stream/Quality/QualityController.ts
+var ORDERED_QUALITY_TIERS = Object.values(QUALITY_TIERS);
+var QualityController = class {
+  constructor(apply, now = () => performance.now(), policy = {}) {
+    __publicField(this, "apply", apply);
+    __publicField(this, "now", now);
+    __publicField(this, "policy");
+    __publicField(this, "active", false);
+    __publicField(this, "index", 0);
+    __publicField(this, "good", 0);
+    __publicField(this, "poor", 0);
+    __publicField(this, "lastSampleAt");
+    __publicField(this, "stableUntil", 0);
+    __publicField(this, "upgradeAfter", 0);
+    __publicField(this, "probeUntil", 0);
+    __publicField(this, "switching", false);
+    __publicField(this, "lifecycle", new AbortController());
+    this.policy = { ...DEFAULT_POLICY, ...policy };
+    for (const value of Object.values(this.policy)) {
+      if (!Number.isFinite(value) || value < 0) throw new Error("Invalid quality policy");
+    }
+    for (const value of [this.policy.poorSamples, this.policy.goodSamples]) {
+      if (!Number.isInteger(value) || value < 1) throw new Error("Sample counts must be positive integers");
+    }
+  }
+  get snapshot() {
+    return Object.freeze({
+      active: this.active,
+      level: this.index + 1,
+      ...ORDERED_QUALITY_TIERS[this.index],
+      switching: this.switching,
+      upgradeAfter: this.upgradeAfter
+    });
+  }
+  /** 传入调用方保存的档位，不在 start 中擅自改写编码配置。 */
+  start(level = 1) {
+    if (!Number.isInteger(level) || level < 1 || level > ORDERED_QUALITY_TIERS.length) {
+      throw new Error("Unsupported quality level");
+    }
+    this.stop();
+    this.lifecycle = new AbortController();
+    this.index = level - 1;
+    this.active = true;
+    this.stableUntil = this.upgradeAfter = this.probeUntil = 0;
+  }
+  /** 取消旧会话的迟到结果；底层尚未完成时仍保持串行限制。 */
+  stop() {
+    this.active = false;
+    this.lifecycle.abort();
+    this.resetSamples();
+  }
+  /** 前台操作期间丢弃累计样本，但保留试升失败后的冷却时间。 */
+  resetSamples() {
+    this.resetCounts();
+    this.lastSampleAt = void 0;
+  }
+  /** 只接收质量事件，不得用定时器重复提交同一份缓存统计。异常由调用方记录。 */
+  async observe(quality, sampleAt = this.now()) {
+    if (!this.active || this.switching || !Number.isFinite(sampleAt)) return;
+    const now = this.now();
+    if (sampleAt > now) return;
+    if (this.lastSampleAt !== void 0) {
+      if (sampleAt <= this.lastSampleAt) return;
+      if (sampleAt - this.lastSampleAt > this.policy.sampleTimeoutMs) this.resetCounts();
+    }
+    this.lastSampleAt = sampleAt;
+    if (now - sampleAt > this.policy.sampleTimeoutMs || sampleAt < this.stableUntil) {
+      this.resetCounts();
+      return;
+    }
+    if (quality === 4 || quality === 5) {
+      this.good = 0;
+      this.poor++;
+      if (this.poor >= this.policy.poorSamples && this.index < ORDERED_QUALITY_TIERS.length - 1) {
+        return this.change(this.index + 1, now < this.probeUntil ? "failedProbe" : "poorNetwork");
+      }
+    } else if (quality === 1 || quality === 2) {
+      this.poor = 0;
+      if (sampleAt < this.upgradeAfter) {
+        this.good = 0;
+        return;
+      }
+      this.good++;
+      if (this.good >= this.policy.goodSamples && this.index > 0) {
+        return this.change(this.index - 1, "probeUpgrade");
+      }
+    } else {
+      this.resetCounts();
+    }
+    return;
+  }
+  resetCounts() {
+    this.good = this.poor = 0;
+  }
+  async change(index, reason) {
+    const lifecycle = this.lifecycle;
+    const change = { from: this.index + 1, to: index + 1, ...ORDERED_QUALITY_TIERS[index], reason };
+    this.switching = true;
+    this.resetCounts();
+    try {
+      await this.apply(change, lifecycle.signal);
+      if (lifecycle.signal.aborted) return;
+      this.index = index;
+      const now = this.now();
+      this.stableUntil = now + this.policy.stabilizationMs;
+      this.probeUntil = reason === "probeUpgrade" ? now + this.policy.probeMs : 0;
+      if (reason === "failedProbe") this.upgradeAfter = now + this.policy.upgradeCooldownMs;
+      return change;
+    } catch (error) {
+      if (!lifecycle.signal.aborted) {
+        this.stableUntil = this.now() + this.policy.stabilizationMs;
+        throw error;
+      }
+      return;
+    } finally {
+      this.switching = false;
+    }
+  }
+};
+
+// src/Stream/Quality/QualityVideoFormat.ts
+function qualityVideoSize(baseline, level) {
+  const tier = Object.values(QUALITY_TIERS)[level - 1];
+  if (!Number.isInteger(level) || !tier) throw new Error("Unsupported quality level");
+  baseline.validate();
+  const scale = tier.width / QUALITY_TIERS.L1.width;
+  const even = (value) => Math.max(2, Math.floor(value / 2) * 2);
+  return { width: even(baseline.width * scale), height: even(baseline.height * scale) };
+}
+function qualityVideoFormat(baseline, level) {
+  const size = qualityVideoSize(baseline, level);
+  const tier = Object.values(QUALITY_TIERS)[level - 1];
+  return new RealtimeVideoFormat({
+    ...baseline,
+    ...size,
+    fps: Math.min(baseline.fps, tier.frameRate)
+  });
+}
+
+// src/Stream/Quality/QualityHistory.ts
+var QualityHistory = class {
+  constructor(model) {
+    __publicField(this, "model", model);
+  }
+  /** 无记录、损坏、SSR 或浏览器禁止存储时使用默认 L2。 */
+  read(direction) {
+    try {
+      const level = Number(globalThis.localStorage.getItem(this.key(direction)));
+      if (this.isValid(level)) return level;
+    } catch {
+    }
+    return INITIAL_QUALITY_LEVEL;
+  }
+  /** 仅在应用成功后调用；下行成功表示信令已发送，不代表服务端已确认生效。 */
+  write(direction, level) {
+    if (!this.isValid(level)) return;
+    try {
+      globalThis.localStorage.setItem(this.key(direction), String(level));
+    } catch {
+    }
+  }
+  key(direction) {
+    return `xmax:quality:v1:agora:${encodeURIComponent(this.model)}:${direction}`;
+  }
+  isValid(level) {
+    return Number.isInteger(level) && level >= 1 && level <= Object.keys(QUALITY_TIERS).length;
+  }
+};
+
 // src/Core/Realtime/RealtimeCoordinator.ts
 function scopeAffects(scope, kind) {
   if (scope === 1 /* all */) {
@@ -6611,6 +7180,10 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
   get currentState() {
     return this.state;
   }
+  /** 后台自动调档仅在没有前台操作或清理时申请操作租约。 */
+  get isBusy() {
+    return this.activeOperation !== void 0 || this.termination !== void 0;
+  }
   /**
    * 设置实时状态监听器；设置后立即回放当前状态。
    *
@@ -7087,7 +7660,7 @@ var XmaxRealtimeConnectionManager = class {
     }
     const refreshVersion = ++this.refreshVersion;
     this.credentialController = new AbortController();
-    const videoFormat = options.localTrack.videoFormat;
+    const videoFormat = options.localVideoFormat ?? options.localTrack.videoFormat;
     if (!videoFormat) {
       throw new XmaxError(
         "INTERNAL_ERROR" /* internalError */,
@@ -7096,7 +7669,9 @@ var XmaxRealtimeConnectionManager = class {
     }
     const publishLocalMedia = options.publishLocalMedia ?? true;
     if (publishLocalMedia) {
-      await streamController.setVideoEncoderConfig(videoFormat);
+      await streamController.updateUplinkVideoFormat(videoFormat);
+      options.ensureCurrent();
+      options.onVideoEncoderConfigured?.();
     }
     options.ensureCurrent();
     let completePublish;
@@ -7243,7 +7818,7 @@ var XmaxRealtimeConnectionManager = class {
       },
       attachHandler: (view) => {
         this.remoteTarget?.setFrameInterpolation?.(void 0);
-        view.isMirrored = this.dependencies.isMirrored();
+        view.isMirrored = false;
         this.remoteTarget = view;
         this.dependencies.onRenderAttached();
         const mediaTrack = track.mediaStreamTrack;
@@ -7259,14 +7834,6 @@ var XmaxRealtimeConnectionManager = class {
       }
     });
   }
-  /**
-   * 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。
-   */
-  updateRemoteMirror() {
-    if (this.remoteTarget) {
-      this.remoteTarget.isMirrored = this.dependencies.isMirrored();
-    }
-  }
   /**
    * 构造当前远端生成结果媒体流。
    */
@@ -7410,6 +7977,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
         taskID,
         videoFormat: options.videoFormat,
         context,
+        ...options.targetSize && { targetSize: options.targetSize },
+        mirror: options.mirror ?? false,
         ...options.onStartSent && { onStartSent: options.onStartSent }
       });
       await this.awaitConfirmation(confirmation, options.signal);
@@ -7436,7 +8005,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     await this.streamController.updateGeneration({
       taskID,
       videoFormat: options.videoFormat,
-      context
+      context,
+      ...options.targetSize && { targetSize: options.targetSize }
     });
     if (this.activeTaskID !== taskID) throw RealtimeCoordinator.cancelledError();
     this.currentContext = context;
@@ -7573,6 +8143,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     __publicField(this, "connectionManager");
     __publicField(this, "generationManager");
     __publicField(this, "streamController");
+    __publicField(this, "qualityController");
+    __publicField(this, "qualityHistory");
+    __publicField(this, "qualityStates", /* @__PURE__ */ new WeakMap());
+    __publicField(this, "downlinkQualityController");
+    /** 无服务端生效 ACK；level/size 表示最后成功发送的目标，而非实际接收规格。 */
+    __publicField(this, "downlinkQualityState");
+    __publicField(this, "adaptiveQualityPending", false);
+    __publicField(this, "adaptiveQualityRevision", 0);
     /**
      * 音量配置
      */
@@ -7611,7 +8189,6 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       sessionService,
       streamController: this.streamController,
       timing: this.launchTimer,
-      isMirrored: () => this.cameraController.currentTrack?.position === "front" /* front */,
       remoteAudioVolume: () => this.storedRemoteAudioVolume,
       onHeartbeatFailure: (sessionID, error) => {
         void this.handleHeartbeatFailure(sessionID, error);
@@ -7627,6 +8204,31 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       errorHandler: this.errorHandler,
       cleanup: (scope, taskID) => this.performCleanup(scope, taskID)
     });
+    if (options.provider === "agora" /* agora */) {
+      this.qualityHistory = new QualityHistory(options.model);
+      this.qualityController = new QualityController(async (change, signal) => {
+        if (signal.aborted || this.currentState.connectionState !== "Generating" /* generating */) {
+          throw new XmaxError("CANCELLED" /* cancelled */, "Adaptive video format update was cancelled");
+        }
+        await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+          const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+          const state2 = track && this.qualityStates.get(track);
+          if (!track || !state2) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Adaptive video baseline is unavailable");
+          const format = qualityVideoFormat(state2.baseline, change.to);
+          await this.streamController.updateUplinkVideoFormat(format);
+          token.ensureCurrent();
+          this.generationVideoFormat ?? (this.generationVideoFormat = state2.baseline);
+          track.updateVideoFormat(format);
+          state2.level = change.to;
+          this.qualityHistory?.write("uplink", change.to);
+        });
+      });
+      this.downlinkQualityController = new QualityController(async (change, signal) => {
+        await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+          await this.applyDownlinkQuality(change.to, token, signal);
+        });
+      });
+    }
     this.streamController.setLocalVideoStatisticsListener((statistics) => {
       if (this.acceptsVideoStatistics) {
         this.localVideoStatistics = statistics ? Object.freeze({ ...statistics }) : void 0;
@@ -7636,6 +8238,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.streamController.setNetworkStatisticsListener((statistics) => {
       if (this.acceptsVideoStatistics) {
         this.networkStatistics = statistics ? Object.freeze({ ...statistics }) : void 0;
+        this.handleAdaptiveQuality(statistics);
         this.notifyNetworkStatistics();
       }
     });
@@ -7663,7 +8266,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = this.generationVideoFormat ?? this.currentLocalTrack?.videoFormat;
+      const format = this.downlinkQualityState?.size ?? this.generationVideoFormat ?? this.currentLocalTrack?.videoFormat;
       const size = format && enabled ? this.mediaService.resolveFrameInterpolationSize(format) : void 0;
       if (enabled && !await this.checkInterpolationSupport(size, token)) {
         token.ensureCurrent();
@@ -7675,6 +8278,43 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       this.applyRemoteInterpolation();
     });
   }
+  /** 手动调试与自动调档使用同一尺寸信令路径，不修改生成或上行配置。 */
+  async adjustDownlinkQuality(direction) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      const controller = this.downlinkQualityController;
+      const state2 = this.downlinkQualityState;
+      if (!controller || !state2 || this.currentState.connectionState !== "Generating" /* generating */ || direction !== "upgrade" && direction !== "downgrade") {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Downlink quality adjustment requires an active Agora generation and a valid direction");
+      }
+      const level = Math.max(1, Math.min(Object.keys(QUALITY_TIERS).length, state2.level + (direction === "upgrade" ? -1 : 1)));
+      if (level === state2.level) return;
+      this.adaptiveQualityRevision++;
+      controller.resetSamples();
+      await this.applyDownlinkQuality(level, token);
+      controller.start(level);
+    });
+  }
+  async applyDownlinkQuality(level, token, signal) {
+    const state2 = this.downlinkQualityState;
+    const ensureActive2 = () => {
+      token.ensureCurrent();
+      if (signal?.aborted || !state2 || state2 !== this.downlinkQualityState || this.currentState.connectionState !== "Generating" /* generating */ || this.currentState.taskID !== state2.taskID) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Target size update was cancelled");
+      }
+    };
+    ensureActive2();
+    if (!state2) return;
+    const size = qualityVideoSize(state2.baseline, level);
+    await this.streamController.updateDownlinkVideoResolution(state2.taskID, size, ensureActive2);
+    ensureActive2();
+    state2.level = level;
+    state2.size = size;
+    this.qualityHistory?.write("downlink", level);
+    if (this.interpolationRequested) {
+      this.interpolationSize = size;
+      this.applyRemoteInterpolation();
+    }
+  }
   /**
    * 根据当前视频尺寸准备插帧，能力不可用时降级为原视频，并在应用前校验租约。
    */
@@ -7834,6 +8474,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 停止接收媒体统计并清空各类快照，仅对曾有数据的统计发出清空通知。
    */
   clearVideoStatistics() {
+    this.qualityController?.stop();
+    this.downlinkQualityController?.stop();
+    this.downlinkQualityState = void 0;
+    this.adaptiveQualityRevision++;
     this.acceptsVideoStatistics = false;
     const hadNetworkStatistics = this.networkStatistics !== void 0;
     this.networkStatistics = void 0;
@@ -7880,6 +8524,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
    *
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @returns 包含本地相机视频轨道的媒体流。
    * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
    */
@@ -7995,7 +8640,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    *
    * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
-  async updateVideoFormat(videoFormat) {
+  async updateUplinkVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
       const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
       const previousFormat = track?.videoFormat;
@@ -8003,10 +8648,86 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera or file video stream is not started");
       }
       videoFormat.validate();
-      await this.streamController.setVideoEncoderConfig(videoFormat);
+      this.qualityController?.stop();
+      await this.streamController.updateUplinkVideoFormat(videoFormat);
       token.ensureCurrent();
       this.generationVideoFormat ?? (this.generationVideoFormat = previousFormat);
       track.updateVideoFormat(videoFormat);
+      this.qualityStates.set(track, { baseline: videoFormat, level: 1 });
+      this.qualityHistory?.write("uplink", 1);
+    });
+  }
+  /** 已连接时仅替换帧率；与其他配置及生命周期操作共享同一操作租约。 */
+  async updateUplinkFrameRate(fps) {
+    await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
+      this.qualityController?.stop();
+      await this.applyUplinkFrameRate(fps, token);
+      const track = this.currentLocalTrack;
+      if (track?.videoFormat) {
+        this.qualityStates.set(track, { baseline: track.videoFormat, level: 1 });
+        this.qualityHistory?.write("uplink", 1);
+      }
+    });
+  }
+  /** 手动仅调帧接口，成功后的当前格式将成为新的自适应 L1 基准。 */
+  async applyUplinkFrameRate(fps, token) {
+    const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+    const previous = track?.videoFormat;
+    const state2 = this.currentState.connectionState;
+    if (!track || !previous || state2 !== "Connected" /* connected */ && state2 !== "Generating" /* generating */) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Frame rate updates require a connected local camera or file stream");
+    }
+    if (!Number.isFinite(fps) || fps <= 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video frame rate must be greater than zero");
+    }
+    const format = await this.streamController.updateUplinkFrameRate(fps);
+    token.ensureCurrent();
+    this.generationVideoFormat ?? (this.generationVideoFormat = previous);
+    track.updateVideoFormat(format);
+  }
+  /** 上下行独立判断；串行应用同一原始事件，避免同时降档争抢配置租约。 */
+  handleAdaptiveQuality(statistics) {
+    const revision = ++this.adaptiveQualityRevision;
+    const controller = this.qualityController;
+    const downlink = this.downlinkQualityController;
+    if (!controller || !downlink) return;
+    const taskID = this.currentState.taskID;
+    if (this.currentState.connectionState !== "Generating" /* generating */ || !taskID) {
+      controller.stop();
+      downlink.stop();
+      return;
+    }
+    if (!statistics || this.coordinator.isBusy || this.adaptiveQualityPending) {
+      controller.resetSamples();
+      downlink.resetSamples();
+      return;
+    }
+    const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+    if (!track) {
+      controller.stop();
+    } else if (!controller.snapshot.active) {
+      const format = track.videoFormat;
+      if (format) {
+        const state3 = this.qualityStates.get(track) ?? { baseline: format, level: 1 };
+        this.qualityStates.set(track, state3);
+        controller.start(state3.level);
+      }
+    }
+    const state2 = this.downlinkQualityState;
+    if (state2 && !downlink.snapshot.active) downlink.start(state2.level);
+    const sampleAt = performance.now();
+    this.adaptiveQualityPending = true;
+    void (async () => {
+      await controller.observe(statistics.uplinkQuality, sampleAt).catch(() => {
+      });
+      if (revision !== this.adaptiveQualityRevision || this.currentState.taskID !== taskID || state2 !== this.downlinkQualityState || this.currentState.connectionState !== "Generating" /* generating */ || this.coordinator.isBusy) {
+        downlink.resetSamples();
+        return;
+      }
+      await downlink.observe(statistics.downlinkQuality, sampleAt).catch(() => {
+      });
+    })().finally(() => {
+      this.adaptiveQualityPending = false;
     });
   }
   /**
@@ -8046,9 +8767,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "cameraSwitch" /* cameraSwitch */,
       void 0,
       async (token) => {
+        this.qualityController?.stop();
         const stream = await this.cameraController.switchCamera();
         token.ensureCurrent();
-        this.connectionManager.updateRemoteMirror();
         return stream;
       }
     );
@@ -8116,6 +8837,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         if (currentState.connectionState === "Generating" /* generating */) {
           await this.generationManager.update(currentState.taskID, {
             videoFormat,
+            targetSize: this.downlinkQualityController ? this.downlinkQualityState?.size : void 0,
             context: options.context
           });
           token.ensureCurrent();
@@ -8153,6 +8875,15 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.clearVideoStatistics();
     await this.coordinator.terminate(1 /* all */);
   }
+  /** 仅为尚无档位记录的本地上行选择初始档位；不应用配置或覆盖重连状态。 */
+  resolveInitialUplinkQuality(track) {
+    if (!this.qualityController) return void 0;
+    if (this.networkVideoController.currentTrack) return void 0;
+    if (this.qualityStates.has(track)) return void 0;
+    const baseline = track.videoFormat;
+    if (!baseline) return void 0;
+    return { baseline, level: this.qualityHistory.read("uplink") };
+  }
   /**
    * 建立实时连接：创建会话、进房发布、启动心跳并准备远端渲染轨道。
    *
@@ -8188,9 +8919,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         });
         beforePublish = () => cameraReady;
       }
+      const initialQuality = this.resolveInitialUplinkQuality(localTrack);
+      const initialFormat = initialQuality ? qualityVideoFormat(initialQuality.baseline, initialQuality.level) : void 0;
       const remote = await this.connectionManager.connect({
         localTrack,
-        remoteVideoFormat: this.generationVideoFormat,
+        remoteVideoFormat: this.generationVideoFormat ?? localTrack.videoFormat,
+        localVideoFormat: initialFormat,
+        onVideoEncoderConfigured: () => {
+          if (!initialQuality || !initialFormat) return;
+          this.generationVideoFormat ?? (this.generationVideoFormat = initialQuality.baseline);
+          localTrack.updateVideoFormat(initialFormat);
+          this.qualityStates.set(localTrack, initialQuality);
+          this.qualityHistory?.write("uplink", initialQuality.level);
+        },
         model: this.options.model,
         includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : !this.networkVideoController.currentTrack && this.cameraController.useMicrophone,
         publishLocalMedia: !this.networkVideoController.currentTrack,
@@ -8218,14 +8959,18 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async performStartGeneration(token, videoFormat, context) {
     token.setFailureScope(0 /* connection */);
-    await this.prepareFrameInterpolation(videoFormat, token);
+    const initialLevel = this.qualityHistory?.read("downlink") ?? 1;
+    const targetSize = this.downlinkQualityController ? qualityVideoSize(videoFormat, initialLevel) : void 0;
+    await this.prepareFrameInterpolation(targetSize ?? videoFormat, token);
     const completeFirstFrame = this.launchTimer.startFirstFrame();
     this.remoteFrameDisplayHandler = () => {
       if (!token.signal.aborted) completeFirstFrame();
     };
     const taskID = await this.generationManager.start({
       videoFormat,
+      targetSize,
       context,
+      mirror: this.currentLocalTrack === this.cameraController.currentTrack && this.cameraController.currentTrack?.position === "front" /* front */,
       signal: token.signal,
       ensureCurrent: () => token.ensureCurrent(),
       onStartSent: this.localVideoController.isActive ? async () => {
@@ -8242,10 +8987,18 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (!sessionID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "Realtime session is unavailable");
     }
+    this.downlinkQualityController?.stop();
+    this.downlinkQualityState = {
+      taskID,
+      baseline: videoFormat,
+      level: initialLevel,
+      size: targetSize ?? { width: videoFormat.width, height: videoFormat.height }
+    };
     await this.coordinator.commit(
       new RealtimeState({ connectionState: "Generating" /* generating */, sessionID, taskID }),
       token
     );
+    this.qualityHistory?.write("downlink", initialLevel);
     const onFinish = this.networkVideoController.onFinish;
     if (this.networkVideoController.currentTrack) {
       this.streamController.activateNetworkVideoCompletion(onFinish && (() => {
@@ -8884,6 +9637,146 @@ var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
   return VideoContentMode2;
 })(VideoContentMode || {});
 
+// src/Render/Video/RenderStatisticsController.ts
+var RenderStatisticsController = class {
+  /**
+   * 绑定用于观察原视频帧的元素，调用 start 后才开始采集。
+   */
+  constructor(video) {
+    __publicField(this, "video", video);
+    /**
+     * 统计回调
+     */
+    __publicField(this, "handler");
+    /**
+     * 帧观察与采样生命周期
+     */
+    __publicField(this, "timer");
+    __publicField(this, "callbackID");
+    __publicField(this, "sequence", 0);
+    /**
+     * 采样窗口与输出方式
+     */
+    __publicField(this, "startedAt", 0);
+    __publicField(this, "originalFrames", 0);
+    __publicField(this, "interpolatedFrames", 0);
+    __publicField(this, "interpolationActive", false);
+    __publicField(this, "previousPresentedFrames");
+  }
+  /**
+   * 独立于统计面板可见性采集；没有监听者时不占用定时器。
+   */
+  start() {
+    if (this.timer !== void 0 || !this.video.srcObject && !this.video.getAttribute("src") || !this.handler || typeof this.video.requestVideoFrameCallback !== "function") {
+      return;
+    }
+    this.reset();
+    const sequence = this.sequence;
+    const observe = () => {
+      this.callbackID = this.video.requestVideoFrameCallback((_now, metadata) => {
+        if (sequence !== this.sequence) {
+          return;
+        }
+        this.callbackID = void 0;
+        if (!this.interpolationActive && !document.hidden) {
+          this.recordVideoFrames(metadata.presentedFrames);
+        } else {
+          this.previousPresentedFrames = void 0;
+        }
+        observe();
+      });
+    };
+    observe();
+    this.timer = setInterval(() => this.sample(), 1e3);
+  }
+  /**
+   * 切换输出方式并清空采样窗口，避免原视频和画布重复计数。
+   */
+  setInterpolationActive(active) {
+    this.interpolationActive = active;
+    this.reset();
+  }
+  /**
+   * 记录实际提交到画布的原帧或插值帧，不统计未呈现的计算结果。
+   */
+  recordCanvasFrame(interpolated) {
+    if (interpolated) {
+      this.interpolatedFrames++;
+    } else {
+      this.originalFrames++;
+    }
+  }
+  /**
+   * 按浏览器累计呈现帧数的增量统计，包含两次回调之间已呈现但未回调的帧。
+   */
+  recordVideoFrames(presentedFrames) {
+    if (!Number.isSafeInteger(presentedFrames) || presentedFrames < 0) {
+      this.previousPresentedFrames = void 0;
+      return;
+    }
+    const previous = this.previousPresentedFrames;
+    this.previousPresentedFrames = presentedFrames;
+    if (previous === void 0 || presentedFrames < previous) {
+      this.originalFrames += presentedFrames > 0 ? 1 : 0;
+      return;
+    }
+    this.originalFrames += presentedFrames - previous;
+  }
+  /**
+   * 取消采样及帧观察，忽略已排队的旧回调并清空对外统计。
+   */
+  stop() {
+    this.sequence++;
+    clearInterval(this.timer);
+    this.timer = void 0;
+    if (this.callbackID !== void 0) {
+      this.video.cancelVideoFrameCallback(this.callbackID);
+    }
+    this.callbackID = void 0;
+    this.reset();
+  }
+  /**
+   * 清空采样计数，避免换流或切换输出方式时混入旧数据。
+   */
+  reset() {
+    this.startedAt = performance.now();
+    this.originalFrames = 0;
+    this.interpolatedFrames = 0;
+    this.previousPresentedFrames = void 0;
+    this.notify(void 0);
+  }
+  /**
+   * 按实际经过的时间计算帧率；没有新呈现时输出 0，后台页面不报告帧率。
+   */
+  sample() {
+    const now = performance.now();
+    const seconds = (now - this.startedAt) / 1e3;
+    if (document.hidden || seconds <= 0) {
+      this.reset();
+      return;
+    }
+    const statistics = Object.freeze({
+      source: this.interpolationActive ? "canvas" : "video",
+      frameRate: (this.originalFrames + this.interpolatedFrames) / seconds,
+      originalFrameRate: this.originalFrames / seconds,
+      interpolatedFrameRate: this.interpolatedFrames / seconds
+    });
+    this.startedAt = now;
+    this.originalFrames = 0;
+    this.interpolatedFrames = 0;
+    this.notify(statistics);
+  }
+  /**
+   * 隔离接入方回调异常，避免影响播放和后续采样。
+   */
+  notify(statistics) {
+    try {
+      this.handler?.(statistics);
+    } catch {
+    }
+  }
+};
+
 // ../../node_modules/.pnpm/framegen@1.4.0/node_modules/framegen/rt.js
 var WG = 8;
 var texBgSeq = 0;
@@ -11047,6 +11940,10 @@ var RemoteVideoFramePipeline = class {
     __publicField(this, "previousPresented");
     __publicField(this, "slowPairs", 0);
     __publicField(this, "active", false);
+    /**
+     * 帧时间基准：媒体时间异常后，本管线持续使用回调时钟，避免反复切换。
+     */
+    __publicField(this, "timeSource", "mediaTime");
     /** vsync 显示节拍：弹出到点的帧并显示最新的一张。 */
     __publicField(this, "tick", (now) => {
       if (this.stopped) return;
@@ -11093,8 +11990,8 @@ var RemoteVideoFramePipeline = class {
       if (!this.loading) void this.initialize();
       return;
     }
-    const time = metadata.mediaTime * 1e3;
-    if (!Number.isFinite(time) || this.previousTime !== void 0 && time <= this.previousTime) return;
+    const time = this.resolveFrameTime(now, metadata);
+    if (time === void 0) return;
     const previous = this.previousTime;
     const interval = previous === void 0 ? 0 : time - previous;
     const consecutive = this.previousPresented === void 0 || metadata.presentedFrames === this.previousPresented + 1;
@@ -11119,6 +12016,22 @@ var RemoteVideoFramePipeline = class {
     }
     this.interpolate(previousSlot, slot, previous, time, interval);
   }
+  /**
+   * 优先使用媒体时间；新帧的媒体时间异常时切换到单调回调时钟。
+   */
+  resolveFrameTime(now, metadata) {
+    if (this.previousPresented !== void 0 && metadata.presentedFrames <= this.previousPresented) {
+      return void 0;
+    }
+    let time = this.timeSource === "mediaTime" ? metadata.mediaTime * 1e3 : now;
+    if (!Number.isFinite(time) || this.previousTime !== void 0 && time <= this.previousTime) {
+      if (this.timeSource === "callback" || !Number.isFinite(now)) return void 0;
+      this.timeSource = "callback";
+      this.resetTimeline(true);
+      time = now;
+    }
+    return time;
+  }
   /** 帧按显示时间升序入队；同一时间的内容后到先出。 */
   enqueue(frame) {
     const index = this.queue.findIndex((queued) => queued.time >= frame.time);
@@ -11145,8 +12058,10 @@ var RemoteVideoFramePipeline = class {
         this.fail(new Error("Interpolation exceeded the GPU frame budget for 5 consecutive pairs"));
         return;
       }
-      if (this.position(performance.now()) >= midpoint) return;
-      this.enqueue({ slot, time: midpoint });
+      if (this.position(performance.now()) >= midpoint) {
+        return;
+      }
+      this.enqueue({ slot, time: midpoint, interpolated: true });
     }).catch((error) => {
       if (!this.stopped) this.fail(error);
     });
@@ -11165,6 +12080,7 @@ var RemoteVideoFramePipeline = class {
     this.displayedTime = frame.time;
     this.canvas.style.visibility = "visible";
     this.setActive(true);
+    this.options.onFramePresented?.(frame.interpolated ?? false);
   }
   async initialize() {
     this.loading = true;
@@ -11194,11 +12110,13 @@ var RemoteVideoFramePipeline = class {
     this.active = active;
     this.options.onActiveChange?.(active);
   }
-  resetTimeline() {
+  resetTimeline(preserveGpuTimeout = false) {
     this.generation++;
     this.queue = [];
-    clearTimeout(this.stallTimer);
-    this.stallTimer = void 0;
+    if (!preserveGpuTimeout) {
+      clearTimeout(this.stallTimer);
+      this.stallTimer = void 0;
+    }
     if (this.raf !== void 0) cancelAnimationFrame(this.raf);
     this.raf = void 0;
     this.anchor = void 0;
@@ -11277,6 +12195,10 @@ var XmaxVideoView = class {
     __publicField(this, "interpolationOptions");
     __publicField(this, "interpolationPipeline");
     __publicField(this, "interpolationCanvas");
+    /**
+     * 呈现统计组件
+     */
+    __publicField(this, "statisticsController");
     /**
      * DOM 挂载状态
      */
@@ -11287,6 +12209,7 @@ var XmaxVideoView = class {
     this.element.style.overflow = "hidden";
     this.element.style.backgroundColor = "black";
     this.videoElement = document.createElement("video");
+    this.statisticsController = new RenderStatisticsController(this.videoElement);
     this.videoElement.autoplay = true;
     this.videoElement.playsInline = true;
     this.videoElement.muted = true;
@@ -11303,6 +12226,20 @@ var XmaxVideoView = class {
   get track() {
     return this.currentTrack;
   }
+  /**
+   * 每秒接收当前视图的呈现统计；换流、卸载或不可统计时返回 undefined。
+   */
+  get renderStatisticsHandler() {
+    return this.statisticsController.handler;
+  }
+  /**
+   * 更新统计回调，不影响播放；移除回调时停止采集。
+   */
+  set renderStatisticsHandler(handler) {
+    this.statisticsController.handler = handler;
+    this.statisticsController.stop();
+    this.startRenderStatistics();
+  }
   /**
    * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
    */
@@ -11362,6 +12299,7 @@ var XmaxVideoView = class {
       });
     }
     this.startInterpolation();
+    this.startRenderStatistics();
     if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
       this.armFrameDisplayNotification();
     }
@@ -11371,6 +12309,7 @@ var XmaxVideoView = class {
    */
   detach() {
     this.detached = true;
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     if (this.videoElement.getAttribute("src")) {
@@ -11382,6 +12321,7 @@ var XmaxVideoView = class {
    * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
    */
   setVideoURL(url) {
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11395,6 +12335,7 @@ var XmaxVideoView = class {
       this.armFrameDisplayNotification();
     }
     this.videoElement.load();
+    this.startRenderStatistics();
   }
   /**
    * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
@@ -11403,6 +12344,7 @@ var XmaxVideoView = class {
     if (this.videoElement.srcObject === stream) {
       return;
     }
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11411,6 +12353,7 @@ var XmaxVideoView = class {
       this.videoElement.autoplay = true;
       this.armFrameDisplayNotification();
       this.startInterpolation();
+      this.startRenderStatistics();
     }
   }
   /**
@@ -11440,7 +12383,18 @@ var XmaxVideoView = class {
     this.interpolationCanvas = canvas;
     this.applyContentMode();
     this.element.appendChild(canvas);
-    const pipeline = new RemoteVideoFramePipeline(this.videoElement, canvas, this.interpolationOptions);
+    const options = this.interpolationOptions;
+    const pipeline = new RemoteVideoFramePipeline(this.videoElement, canvas, {
+      ...options,
+      onActiveChange: (active) => {
+        this.statisticsController.setInterpolationActive(active);
+        options.onActiveChange?.(active);
+      },
+      onFramePresented: (interpolated) => {
+        this.statisticsController.recordCanvasFrame(interpolated);
+        options.onFramePresented?.(interpolated);
+      }
+    });
     this.interpolationPipeline = pipeline;
     pipeline.start();
   }
@@ -11475,6 +12429,7 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.statisticsController.stop();
     const track = this.currentTrack;
     if (track) {
       VideoRenderRegistry.binding(track)?.detachHandler(this);
@@ -11540,6 +12495,12 @@ var XmaxVideoView = class {
       this.interpolationCanvas.style.transform = this.mirrored ? "scaleX(-1)" : "";
     }
   }
+  /**
+   * 视图未卸载时启动呈现统计，采样及媒体就绪检查由统计组件负责。
+   */
+  startRenderStatistics() {
+    if (!this.detached) this.statisticsController.start();
+  }
 };
 
 // src/Render/Video/XmaxRealtimeVideoView.ts
@@ -11739,4 +12700,4 @@ export {
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-VMJXIVUF.js.map
+//# sourceMappingURL=chunk-4O5BSMUX.js.map