@xmaxai/web-sdk 1.0.5 → 1.0.6

package/dist/{chunk-VMJXIVUF.js → chunk-PLFWPS5A.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.6";
 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,59 @@ 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/RTC/Agora/AgoraRtcManager.ts
 var _AgoraRtcManager = class _AgoraRtcManager {
   /**
@@ -1335,6 +1384,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __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 +1404,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,6 +1474,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     this.clearRoom();
     this.client = void 0;
     client?.removeAllListeners();
+    this.releaseCameraSender();
     this.camera?.close();
     this.microphone?.close();
     this.externalVideo?.close();
@@ -1458,6 +1513,16 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         throw this.cancelled();
       }
       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) {
       throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
@@ -1470,6 +1535,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const camera = this.requireCamera();
     await this.run(() => camera.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
     if (this.camera !== camera) throw this.cancelled();
+    if (this.videoPublishRequested) await this.restoreCameraSender(camera);
     return camera.getMediaStreamTrack();
   }
   /**
@@ -1477,6 +1543,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async stopCameraCapture() {
     const camera = this.camera;
+    this.releaseCameraSender();
     this.camera = void 0;
     camera?.close();
   }
@@ -1512,11 +1579,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, { ...config, ...rtcOrientedVideoSize(config) }, ensureActive2);
+        }
+        this.cameraSenderConfiguration = { ...config };
+      }));
+      return;
+    }
+    const encodingSize = config;
     await this.run(async () => {
       await camera.setEncoderConfiguration({
         width: encodingSize.width,
@@ -1525,9 +1607,37 @@ 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, { ...config, ...rtcOrientedVideoSize(config) }, ensureActive2);
+    });
+  }
+  releaseCameraSender() {
+    if (this.cameraTransceiverListener) this.camera?.off("transceiver-updated", this.cameraTransceiverListener);
+    this.cameraTransceiverListener = void 0;
+    this.cameraSenderConfiguration = void 0;
+  }
   /**
    * 使用会话下发的字符串频道与 UID 入房；不采信后端区域覆盖。
    */
@@ -1645,6 +1755,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 +1785,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 +1983,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 +2007,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 +2033,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);
@@ -5043,6 +5159,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 +5612,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 +5764,7 @@ var _EncodingController = class _EncodingController {
      * 基础层组件
      */
     __publicField(this, "rtcManager");
+    __publicField(this, "lastAppliedConfiguration");
     this.rtcManager = options.rtcManager;
   }
   /**
@@ -5681,14 +5800,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 +6069,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 +6161,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 +6235,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 +6657,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 +6948,10 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
   get currentState() {
     return this.state;
   }
+  /** 后台自动调档仅在没有前台操作或清理时申请操作租约。 */
+  get isBusy() {
+    return this.activeOperation !== void 0 || this.termination !== void 0;
+  }
   /**
    * 设置实时状态监听器；设置后立即回放当前状态。
    *
@@ -7087,7 +7428,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 +7437,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 +7586,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 +7602,6 @@ var XmaxRealtimeConnectionManager = class {
       }
     });
   }
-  /**
-   * 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。
-   */
-  updateRemoteMirror() {
-    if (this.remoteTarget) {
-      this.remoteTarget.isMirrored = this.dependencies.isMirrored();
-    }
-  }
   /**
    * 构造当前远端生成结果媒体流。
    */
@@ -7410,6 +7745,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 +7773,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 +7911,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 +7957,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 +7972,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 +8006,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 +8034,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 +8046,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 +8242,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;
@@ -7995,7 +8407,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 +8415,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 +8534,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 +8604,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 +8642,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 +8686,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 +8726,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 +8754,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 +9404,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 +11707,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 +11757,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 +11783,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 +11825,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 +11847,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 +11877,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 +11962,10 @@ var XmaxVideoView = class {
     __publicField(this, "interpolationOptions");
     __publicField(this, "interpolationPipeline");
     __publicField(this, "interpolationCanvas");
+    /**
+     * 呈现统计组件
+     */
+    __publicField(this, "statisticsController");
     /**
      * DOM 挂载状态
      */
@@ -11287,6 +11976,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 +11993,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 +12066,7 @@ var XmaxVideoView = class {
       });
     }
     this.startInterpolation();
+    this.startRenderStatistics();
     if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
       this.armFrameDisplayNotification();
     }
@@ -11371,6 +12076,7 @@ var XmaxVideoView = class {
    */
   detach() {
     this.detached = true;
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     if (this.videoElement.getAttribute("src")) {
@@ -11382,6 +12088,7 @@ var XmaxVideoView = class {
    * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
    */
   setVideoURL(url) {
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11395,6 +12102,7 @@ var XmaxVideoView = class {
       this.armFrameDisplayNotification();
     }
     this.videoElement.load();
+    this.startRenderStatistics();
   }
   /**
    * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
@@ -11403,6 +12111,7 @@ var XmaxVideoView = class {
     if (this.videoElement.srcObject === stream) {
       return;
     }
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
@@ -11411,6 +12120,7 @@ var XmaxVideoView = class {
       this.videoElement.autoplay = true;
       this.armFrameDisplayNotification();
       this.startInterpolation();
+      this.startRenderStatistics();
     }
   }
   /**
@@ -11440,7 +12150,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 +12196,7 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.statisticsController.stop();
     const track = this.currentTrack;
     if (track) {
       VideoRenderRegistry.binding(track)?.detachHandler(this);
@@ -11540,6 +12262,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 +12467,4 @@ export {
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-VMJXIVUF.js.map
+//# sourceMappingURL=chunk-PLFWPS5A.js.map