@xmaxai/web-sdk 1.0.4 → 1.0.6

package/dist/{chunk-FMAQXPTE.js → chunk-PLFWPS5A.js}

@@ -12,9 +12,16 @@ var API_BASE_URLS = {
   ["china" /* china */]: "https://cloud.xmax.22duck.cn/open/api/v1",
   ["global" /* global */]: "https://api.xmax.cloud/open/api/v1"
 };
+var NON_REALTIME_API_BASE_URLS = {
+  ["china" /* china */]: "https://api.xmaxai.com/open/api/v1",
+  ["global" /* global */]: "https://api.xmax.ai/open/api/v1"
+};
 function apiBaseURL(environment) {
   return API_BASE_URLS[environment];
 }
+function nonRealtimeApiBaseURL(environment) {
+  return NON_REALTIME_API_BASE_URLS[environment];
+}
 
 // src/Foundation/Logging/XmaxLogger.ts
 var XmaxLoggerOption = /* @__PURE__ */ ((XmaxLoggerOption2) => {
@@ -198,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.4";
+var XMAX_SDK_VERSION = "1.0.6";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -268,8 +275,24 @@ var _ApiService = class _ApiService {
    */
   async request(method, path, body, options) {
     this.validateConfiguration();
+    if (options?.signal?.aborted) {
+      throw new XmaxError("CANCELLED" /* cancelled */, "API request was cancelled");
+    }
     const request = this.makeRequest(method, path, body, options);
     const startedAt = Date.now();
+    const timeoutSignal = request.init.signal;
+    const controller = new AbortController();
+    const abortTimeout = () => controller.abort(timeoutSignal.reason);
+    const abortCaller = () => controller.abort(new DOMException("Cancelled", "AbortError"));
+    timeoutSignal.addEventListener("abort", abortTimeout, { once: true });
+    options?.signal?.addEventListener("abort", abortCaller, { once: true });
+    request.init.signal = controller.signal;
+    if (timeoutSignal.aborted) {
+      abortTimeout();
+    }
+    if (options?.signal?.aborted) {
+      abortCaller();
+    }
     let status;
     let text;
     try {
@@ -280,6 +303,9 @@ var _ApiService = class _ApiService {
       const mapped = _ApiService.transportError(error);
       this.logFailure(method, path, mapped, startedAt);
       throw mapped;
+    } finally {
+      timeoutSignal.removeEventListener("abort", abortTimeout);
+      options?.signal?.removeEventListener("abort", abortCaller);
     }
     try {
       const value = _ApiService.parseResponse(text, status);
@@ -297,8 +323,8 @@ var _ApiService = class _ApiService {
   /**
    * 发送 GET 请求。
    */
-  get(path) {
-    return this.request("GET" /* get */, path);
+  get(path, options) {
+    return this.request("GET" /* get */, path, void 0, options);
   }
   /**
    * 发送 POST 请求。
@@ -405,7 +431,8 @@ var _ApiService = class _ApiService {
       });
     }
     const ok = status >= 200 && status < 300;
-    if (!ok || envelope.success !== true) {
+    const succeeded = envelope.success === true || envelope.success === void 0 && envelope.code === 200;
+    if (!ok || !succeeded) {
       const message = envelope.message?.trim();
       throw new XmaxError(
         "API_ERROR" /* apiError */,
@@ -561,50 +588,68 @@ var RealtimeVideoFormat = class _RealtimeVideoFormat {
   }
 };
 
+// src/Foundation/RTC/RtcProvider.ts
+var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
+  RtcProvider2["trtc"] = "trtc";
+  RtcProvider2["agora"] = "agora";
+  RtcProvider2["vertc"] = "vertc";
+  return RtcProvider2;
+})(RtcProvider || {});
+
 // src/Service/Realtime/RealtimeModel.ts
 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 || {});
+function isKnownModel(model) {
+  if (typeof model !== "string" || !model.trim()) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Realtime model must be a non-empty string");
+  }
+  return Object.values(RealtimeModel).includes(model);
+}
+function modelDefaults(model) {
+  return isKnownModel(model) ? model : "x2.1-preview" /* x2_1_preview */;
+}
+var MODEL_DISPLAY_NAMES = {
+  ["x2.0" /* x2_0 */]: "X2.0",
+  ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
+  ["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.1-preview" /* x2_1_preview */]: [
-    { width: 1024, height: 1920 },
-    { width: 1920, height: 1024 }
-  ],
-  ["x2.0-agora" /* x2_0_agora */]: [
+  ["x2.0" /* x2_0 */]: [],
+  ["x2.0-trtc" /* x2_0_trtc */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ],
-  ["x2.0" /* x2_0 */]: [],
-  ["x2.0-trtc" /* x2_0_trtc */]: [
+  ["x2.1-preview" /* x2_1_preview */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
-  ["x2.1-preview" /* x2_1_preview */]: 21e5,
-  ["x2.0-agora" /* x2_0_agora */]: 21e5,
   ["x2.0" /* x2_0 */]: 128e4,
-  ["x2.0-trtc" /* x2_0_trtc */]: 21e5
+  ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
+  ["x2.1-preview" /* x2_1_preview */]: 21e5
 };
+function modelDisplayName(model) {
+  return isKnownModel(model) ? MODEL_DISPLAY_NAMES[model] : model;
+}
 function modelBaseURL(model) {
-  return MODEL_BASE_URLS[model];
+  return MODEL_BASE_URLS[modelDefaults(model)];
 }
 function resolutionBuckets(model) {
-  return RESOLUTION_BUCKETS[model];
+  return RESOLUTION_BUCKETS[modelDefaults(model)];
 }
 function minimumInputPixels(_model) {
   return 6e5;
 }
 function maximumInputPixels(model) {
-  return MAXIMUM_INPUT_PIXELS[model];
+  return MAXIMUM_INPUT_PIXELS[modelDefaults(model)];
 }
 function inputSizeAlignment(_model) {
   return 32;
@@ -613,11 +658,23 @@ function defaultFrameRate(_model) {
   return 30;
 }
 function defaultCameraVideoFormat(model) {
-  if (model === "x2.0" /* x2_0 */) {
+  if (modelDefaults(model) === "x2.0" /* x2_0 */) {
     return new RealtimeVideoFormat({ width: 832, height: 1472, fps: 30 });
   }
   return new RealtimeVideoFormat({ width: 1024, height: 1920, fps: 30 });
 }
+var MODEL_RTC_PROVIDERS = {
+  ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
+  ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
+  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */])
+};
+function supportedRtcProviders(model) {
+  return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
+}
+var CUSTOM_MODEL_RTC_PROVIDERS = Object.freeze([
+  ...MODEL_RTC_PROVIDERS["x2.1-preview" /* x2_1_preview */],
+  ...Object.values(RtcProvider).filter((provider) => !MODEL_RTC_PROVIDERS["x2.1-preview" /* x2_1_preview */].includes(provider))
+]);
 
 // src/Foundation/Media/Video/FrameInterpolationSupport.ts
 async function frameInterpolationAdapter(size) {
@@ -802,7 +859,14 @@ var CONTENT_TYPES = {
   gif: "image/gif",
   bmp: "image/bmp",
   heic: "image/heic",
-  heif: "image/heif"
+  heif: "image/heif",
+  mp4: "video/mp4",
+  m4v: "video/mp4",
+  mov: "video/quicktime",
+  webm: "video/webm",
+  avi: "video/x-msvideo",
+  mkv: "video/x-matroska",
+  ogv: "video/ogg"
 };
 var StorageService = class _StorageService {
   /**
@@ -836,6 +900,81 @@ var StorageService = class _StorageService {
    * 上传图片并返回访问地址。
    */
   async uploadImage(options) {
+    return this.upload(options, "Image");
+  }
+  /**
+   * 普通上传原始视频并返回访问地址，不进行转码、压缩或分片。
+   */
+  async uploadVideo(options) {
+    return this.upload(options, "Video");
+  }
+  /**
+   * 下载原始视频文件并交给浏览器保存，支持取消网络下载。
+   */
+  async downloadVideo(options) {
+    const fileName = _StorageService.validateFileName(options.fileName);
+    let url;
+    try {
+      url = new URL(options.url.trim());
+    } catch {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Invalid video download URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video download requires an HTTP(S) URL without embedded credentials");
+    }
+    if (typeof document === "undefined" || !document.body) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video saving requires a browser document");
+    }
+    let objectURL;
+    let link;
+    let saveRequested = false;
+    try {
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      const response = await fetch(options.url.trim(), { credentials: "omit", signal: options.signal });
+      if (!response.ok) {
+        throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, "Video download failed", { httpStatus: response.status });
+      }
+      const data = await response.blob();
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      if (data.size === 0) {
+        throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, "Downloaded video is empty");
+      }
+      objectURL = URL.createObjectURL(data);
+      link = document.createElement("a");
+      link.href = objectURL;
+      link.download = fileName;
+      link.hidden = true;
+      document.body.appendChild(link);
+      link.click();
+      saveRequested = true;
+    } catch (error) {
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      if (error instanceof XmaxError) {
+        throw error;
+      }
+      throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, error instanceof Error ? error.message : String(error));
+    } finally {
+      link?.remove();
+      if (objectURL) {
+        const resourceURL = objectURL;
+        if (saveRequested) {
+          setTimeout(() => URL.revokeObjectURL(resourceURL), 6e4);
+        } else {
+          URL.revokeObjectURL(resourceURL);
+        }
+      }
+    }
+  }
+  /**
+   * 获取临时凭证并通过 COS putObject 上传文件，统一处理进度、结果和错误。
+   */
+  async upload(options, mediaType) {
     const startedAt = Date.now();
     try {
       const safeName = _StorageService.validateFileName(options.fileName);
@@ -844,7 +983,7 @@ var StorageService = class _StorageService {
       if (body.size === 0) {
         throw new XmaxError(
           "INVALID_CONFIGURATION" /* invalidConfiguration */,
-          "Image data cannot be empty"
+          `${mediaType} data cannot be empty`
         );
       }
       const temporary = await this.fetchStorageConfiguration();
@@ -982,7 +1121,7 @@ var StorageService = class _StorageService {
     if (!safeName || safeName.includes("/") || safeName.includes("\\")) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
-        "Invalid file name for storage upload"
+        "Invalid file name for storage operation"
       );
     }
     return safeName;
@@ -1121,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 */);
@@ -1168,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 {
   /**
@@ -1185,6 +1382,12 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __publicField(this, "lifecycle", 0);
     __publicField(this, "camera");
     __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);
     /**
@@ -1201,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());
     /**
@@ -1267,12 +1471,16 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async destroy() {
     this.lifecycle++;
     const client = this.client;
-    this.listener = void 0;
     this.clearRoom();
     this.client = void 0;
     client?.removeAllListeners();
+    this.releaseCameraSender();
     this.camera?.close();
     this.microphone?.close();
+    this.externalVideo?.close();
+    this.externalAudio?.close();
+    this.externalVideo = void 0;
+    this.externalAudio = void 0;
     this.camera = void 0;
     this.microphone = void 0;
     const sdk = this.sdk;
@@ -1291,7 +1499,9 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async startCameraCapture(options) {
     const client = this.requireClient();
-    if (this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is already running");
+    if (this.camera || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "A local video source is already active");
+    }
     try {
       const captureSize = rtcOrientedVideoSize(options);
       const camera = await this.sdk.createCameraVideoTrack({
@@ -1303,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 */);
@@ -1315,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();
   }
   /**
@@ -1322,15 +1543,62 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async stopCameraCapture() {
     const camera = this.camera;
+    this.releaseCameraSender();
     this.camera = void 0;
     camera?.close();
   }
   /**
-   * 应用公共编码配置，补偿移动端竖屏的宽高转置。
+   * 将外部原生轨包装为 Agora 本地轨，不申请设备权限；失败时释放本次克隆。
+   */
+  async setExternalMediaTracks(tracks) {
+    this.requireClient();
+    if (this.camera || 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")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media requires live video and optional audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    let audio;
+    let wrappedVideo;
+    let wrappedAudio;
+    try {
+      audio = tracks.audioTrack?.clone();
+      wrappedVideo = this.sdk.createCustomVideoTrack({ mediaStreamTrack: video });
+      if (audio) {
+        wrappedAudio = this.sdk.createCustomAudioTrack({ mediaStreamTrack: audio, encoderConfig: "music_standard" });
+      }
+      this.externalVideo = wrappedVideo;
+      this.externalAudio = wrappedAudio;
+    } catch (error) {
+      wrappedVideo?.close();
+      wrappedAudio?.close();
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
+  }
+  /**
+   * 摄像头实验走原生 sender（发布前暂存）；外部视频仍走 Agora 编码配置。
    */
   async configureVideoEncoding(config) {
-    const camera = this.requireCamera();
-    const encodingSize = rtcOrientedVideoSize(config);
+    const camera = this.requireLocalVideo();
+    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,
@@ -1339,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 入房；不采信后端区域覆盖。
    */
@@ -1349,7 +1645,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     await this.rejoinTask?.catch(() => {
     });
     const client = this.requireClient();
-    if (configuration.provider !== "agora" || this.connection) {
+    if (configuration.provider !== "agora" /* agora */ || this.connection) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Agora credentials and an idle room are required");
     }
     const version = ++this.roomVersion;
@@ -1385,7 +1681,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (signal?.aborted) throw this.cancelled();
     const current = this.connection;
     const client = this.requireClient();
-    if (!current || config.provider !== "agora" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+    if (!current || config.provider !== "agora" /* agora */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "Agora session binding changed");
     }
     const version = this.roomVersion;
@@ -1454,12 +1750,15 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       await this.run(() => client.leave());
       throw this.cancelled();
     }
-    if (this.videoPublishRequested && this.camera) {
-      await this.run(() => client.publish(this.camera));
+    const video = this.externalVideo ?? this.camera;
+    const audio = this.externalVideo ? this.externalAudio : this.microphone;
+    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 && this.microphone) {
-      await this.run(() => client.publish(this.microphone));
+    if (this.audioPublishRequested && audio) {
+      await this.run(() => client.publish(audio));
       this.ensureRoomCurrent(client, version);
     }
     for (const user of client.remoteUsers) {
@@ -1480,12 +1779,13 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async publishLocalVideo() {
     const client = this.requireClient();
-    const camera = this.requireCamera();
+    const camera = this.requireLocalVideo();
     this.videoPublishRequested = true;
     await this.rejoinOperation;
     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));
   }
   /**
    * 停止视频发布但保留采集与预览。
@@ -1493,10 +1793,13 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async unpublishLocalVideo() {
     this.videoPublishRequested = false;
     if (this.rejoinTask || this.tokenExpired) return;
-    if (this.client && this.camera) await this.run(() => this.client.unpublish(this.camera));
+    const video = this.externalVideo ?? this.camera;
+    if (this.client && video) {
+      await this.run(() => this.client.unpublish(video));
+    }
   }
   /**
-   * 首次发布时申请麦克风；取消后的迟到采集立即释放。
+   * 外部源只发布提供的音轨；相机源首次发布时申请麦克风，迟到采集立即释放。
    */
   async publishLocalAudio() {
     const client = this.requireClient();
@@ -1504,6 +1807,13 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     await this.rejoinOperation;
     const version = this.roomVersion;
     if (client !== this.client || !this.audioPublishRequested) throw this.cancelled();
+    if (this.externalVideo) {
+      const audio = this.externalAudio;
+      if (audio && !client.localTracks.includes(audio)) {
+        await this.run(() => client.publish(audio));
+      }
+      return;
+    }
     try {
       if (!this.microphone) {
         const track = await this.sdk.createMicrophoneAudioTrack();
@@ -1524,7 +1834,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async unpublishLocalAudio() {
     this.audioPublishRequested = false;
     if (this.rejoinTask || this.tokenExpired) return;
-    if (this.client && this.microphone) await this.run(() => this.client.unpublish(this.microphone));
+    const audio = this.externalVideo ? this.externalAudio : this.microphone;
+    if (this.client && audio) {
+      await this.run(() => this.client.unpublish(audio));
+    }
   }
   /**
    * 订阅远端主视频并返回原生轨道，不创建额外播放视图。
@@ -1670,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) => {
@@ -1693,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;
@@ -1717,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);
@@ -1755,6 +2072,16 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
     return this.camera;
   }
+  /**
+   * 获取当前可编码、发布的视频轨，不要求来源为摄像头。
+   */
+  requireLocalVideo() {
+    const video = this.externalVideo ?? this.camera;
+    if (!video) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video source is not prepared");
+    }
+    return video;
+  }
   /**
    * 执行声网操作并统一错误类型。
    */
@@ -1787,14 +2114,6 @@ var _AgoraRtcManager = class _AgoraRtcManager {
 __publicField(_AgoraRtcManager, "regions", /* @__PURE__ */ new Map());
 var AgoraRtcManager = _AgoraRtcManager;
 
-// src/Foundation/RTC/RtcProvider.ts
-var RtcProvider = /* @__PURE__ */ ((RtcProvider2) => {
-  RtcProvider2["trtc"] = "trtc";
-  RtcProvider2["agora"] = "agora";
-  RtcProvider2["vertc"] = "vertc";
-  return RtcProvider2;
-})(RtcProvider || {});
-
 // src/Foundation/RTC/TRTC/RtcEngineManager.ts
 var RtcEngineLease = class {
   /**
@@ -2072,6 +2391,11 @@ var TrtcRtcManager = class {
      */
     __publicField(this, "isCapturing", false);
     __publicField(this, "isAudioCapturing", false);
+    /**
+     * 外部媒体的克隆轨；原始轨道由媒体源管理。
+     */
+    __publicField(this, "externalVideo");
+    __publicField(this, "externalAudio");
     /**
      * 房间状态
      */
@@ -2106,13 +2430,18 @@ var TrtcRtcManager = class {
   async destroy() {
     const lease = this.lease;
     this.lease = void 0;
-    this.eventListener = void 0;
+    const externalVideo = this.externalVideo;
+    const externalAudio = this.externalAudio;
+    this.externalVideo = void 0;
+    this.externalAudio = void 0;
     this.isCapturing = false;
     this.isAudioCapturing = false;
     this.isInRoom = false;
     this.removeStatsListeners?.();
     this.removeStatsListeners = void 0;
     if (!lease) {
+      externalVideo?.stop();
+      externalAudio?.stop();
       return;
     }
     try {
@@ -2123,8 +2452,56 @@ var TrtcRtcManager = class {
       await lease.engine.stopLocalVideo();
     } catch {
     }
+    externalVideo?.stop();
+    externalAudio?.stop();
     this.engineManager.release(lease);
   }
+  /**
+   * 准备外部音视频轨但不发布；失败时释放克隆轨，不影响原始媒体源。
+   */
+  async setExternalMediaTracks(tracks) {
+    const engine = this.requireEngine();
+    if (this.isCapturing || this.isAudioCapturing || 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")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media tracks must be live video/audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    this.externalVideo = video;
+    let audio;
+    try {
+      audio = tracks.audioTrack?.clone();
+      this.externalAudio = audio;
+      await engine.startLocalVideo({ publish: false, option: { videoTrack: video } });
+      if (this.lease?.engine !== engine) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
+      }
+      if (audio) {
+        await engine.startLocalAudio({
+          publish: false,
+          option: { audioTrack: audio, echoCancellation: false, autoGainControl: false, noiseSuppression: false }
+        });
+        if (this.lease?.engine !== engine) {
+          throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
+        }
+      }
+    } catch (error) {
+      if (this.lease?.engine === engine) {
+        await engine.stopLocalAudio().catch(() => {
+        });
+        await engine.stopLocalVideo().catch(() => {
+        });
+      }
+      if (this.externalVideo === video) {
+        this.externalVideo = void 0;
+        this.externalAudio = void 0;
+      }
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
+  }
   /**
    * 启动摄像头采集（不发布）。
    *
@@ -2133,7 +2510,7 @@ var TrtcRtcManager = class {
    */
   async startCameraCapture(options) {
     const engine = this.requireEngine();
-    if (this.isCapturing) {
+    if (this.isCapturing || this.externalVideo) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
         "Camera capture is already running"
@@ -2203,6 +2580,9 @@ var TrtcRtcManager = class {
    * 停止摄像头采集；引擎未初始化或采集未启动时不产生效果。
    */
   async stopCameraCapture() {
+    if (this.externalVideo) {
+      return;
+    }
     const engine = this.lease?.engine;
     this.isCapturing = false;
     if (!engine) {
@@ -2220,7 +2600,7 @@ var TrtcRtcManager = class {
    * @throws 引擎未初始化、进房参数无效或进房失败时抛出错误。
    */
   async joinRoom(configuration) {
-    if (configuration.provider !== "trtc") {
+    if (configuration.provider !== "trtc" /* trtc */) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "TRTC credentials required");
     }
     const engine = this.requireEngine();
@@ -2276,18 +2656,18 @@ var TrtcRtcManager = class {
    * TRTC 只接受单一目标码率，以 `minimumBitrate`（流畅优先档）作为目标码率；
    * 编码策略偏好映射为 TRTC 弱网偏好。
    *
-   * @throws 摄像头采集未启动或编码参数配置失败时抛出错误。
+   * @throws 本地视频未准备或编码参数配置失败时抛出错误。
    */
   async configureVideoEncoding(configuration) {
     const engine = this.requireEngine();
-    if (!this.isCapturing) {
+    if (!this.isCapturing && !this.externalVideo) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
-        "Camera capture is not running"
+        "Local video is not prepared"
       );
     }
     try {
-      const encodingSize = rtcOrientedVideoSize({
+      const encodingSize = this.externalVideo ? configuration : rtcOrientedVideoSize({
         width: configuration.width,
         height: configuration.height
       });
@@ -2309,14 +2689,14 @@ var TrtcRtcManager = class {
   /**
    * 发布本地视频流。
    *
-   * @throws 摄像头采集未启动或发布失败时抛出错误。
+   * @throws 本地视频未准备或发布失败时抛出错误。
    */
   async publishLocalVideo() {
     const engine = this.requireEngine();
-    if (!this.isCapturing) {
+    if (!this.isCapturing && !this.externalVideo) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
-        "Camera capture is not running"
+        "Local video is not prepared"
       );
     }
     try {
@@ -2330,7 +2710,7 @@ var TrtcRtcManager = class {
    */
   async unpublishLocalVideo() {
     const engine = this.lease?.engine;
-    if (!engine || !this.isCapturing) {
+    if (!engine || !this.isCapturing && !this.externalVideo) {
       return;
     }
     try {
@@ -2340,14 +2720,18 @@ var TrtcRtcManager = class {
     }
   }
   /**
-   * 发布本地音频流；首次调用时启动麦克风采集。
+   * 发布文件音频或麦克风；无文件音轨时不启动麦克风。
    *
    * @throws 引擎未初始化、麦克风权限被拒绝或发布失败时抛出错误。
    */
   async publishLocalAudio() {
     const engine = this.requireEngine();
     try {
-      if (!this.isAudioCapturing) {
+      if (this.externalVideo) {
+        if (this.externalAudio) {
+          await engine.updateLocalAudio({ publish: true });
+        }
+      } else if (!this.isAudioCapturing) {
         await engine.startLocalAudio();
         this.isAudioCapturing = true;
       } else {
@@ -2362,7 +2746,7 @@ var TrtcRtcManager = class {
    */
   async unpublishLocalAudio() {
     const engine = this.lease?.engine;
-    if (!engine || !this.isAudioCapturing) {
+    if (!engine || !this.isAudioCapturing && !this.externalAudio) {
       return;
     }
     try {
@@ -2540,19 +2924,19 @@ var TrtcRtcManager = class {
       source.off(RTC_EVENT.networkQuality, onNetworkQuality);
     };
     source.on(RTC_EVENT.remoteVideoAvailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (this.lease?.engine !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
       this.eventListener?.onRemoteVideoPublished(event.userId, true);
     });
     source.on(RTC_EVENT.remoteVideoUnavailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (this.lease?.engine !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
       this.eventListener?.onRemoteVideoPublished(event.userId, false);
     });
     source.on(RTC_EVENT.customMessage, (event) => {
-      if (event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
+      if (this.lease?.engine !== engine || event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
         return;
       }
       let message;
@@ -2645,6 +3029,11 @@ var VeRtcManager = class {
     __publicField(this, "captureVersion", 0);
     __publicField(this, "camera");
     __publicField(this, "microphone", false);
+    /**
+     * 外部媒体的克隆轨；原始轨道由媒体源管理。
+     */
+    __publicField(this, "externalVideo");
+    __publicField(this, "externalAudio");
     __publicField(this, "connection");
     __publicField(this, "joined", false);
     __publicField(this, "roomVersion", 0);
@@ -2700,18 +3089,76 @@ var VeRtcManager = class {
     this.captureVersion++;
     const engine = this.engine;
     const sdk = this.sdk;
-    this.listener = void 0;
     this.clearRoom();
     this.engine = void 0;
     this.sdk = void 0;
     this.camera = void 0;
     this.microphone = false;
     engine?.removeAllListeners();
-    if (engine && sdk) sdk.default.destroyEngine(engine);
+    try {
+      if (engine && sdk) sdk.default.destroyEngine(engine);
+    } finally {
+      this.externalVideo?.stop();
+      this.externalAudio?.stop();
+      this.externalVideo = void 0;
+      this.externalAudio = void 0;
+    }
+  }
+  /**
+   * 将克隆的文件音视频轨绑定到主流，不采集设备、不自动发布。
+   */
+  async setExternalMediaTracks(tracks) {
+    const engine = this.requireEngine();
+    const sdk = this.sdk;
+    if (this.camera || 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")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media tracks must be live video/audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    this.externalVideo = video;
+    let audio;
+    const index = sdk.StreamIndex.STREAM_INDEX_MAIN;
+    const ensureCurrent = () => {
+      if (this.engine !== engine || this.externalVideo !== video) {
+        throw this.cancelled();
+      }
+    };
+    try {
+      audio = tracks.audioTrack?.clone();
+      this.externalAudio = audio;
+      await engine.setVideoSourceType(index, sdk.VideoSourceType.VIDEO_SOURCE_TYPE_EXTERNAL);
+      ensureCurrent();
+      await engine.setExternalVideoTrack(index, video);
+      ensureCurrent();
+      if (audio) {
+        await engine.setAudioSourceType(index, sdk.AudioSourceType.AUDIO_SOURCE_TYPE_EXTERNAL);
+        ensureCurrent();
+        await engine.setExternalAudioTrack(index, audio);
+        ensureCurrent();
+      }
+    } catch (error) {
+      if (this.engine === engine) {
+        await engine.setAudioSourceType(index, sdk.AudioSourceType.AUDIO_SOURCE_TYPE_INTERNAL).catch(() => {
+        });
+        await engine.setVideoSourceType(index, sdk.VideoSourceType.VIDEO_SOURCE_TYPE_INTERNAL).catch(() => {
+        });
+      }
+      if (this.externalVideo === video) {
+        this.externalVideo = void 0;
+        this.externalAudio = void 0;
+      }
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
   }
   async startCameraCapture(options) {
     const engine = this.requireEngine();
-    if (this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is already running");
+    if (this.camera || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is already prepared");
+    }
     const version = ++this.captureVersion;
     await this.run(() => engine.setVideoEncoderConfig({
       ...rtcOrientedVideoSize({ width: options.width, height: options.height }),
@@ -2751,15 +3198,20 @@ var VeRtcManager = class {
     return track;
   }
   async stopCameraCapture() {
+    if (this.externalVideo) {
+      return;
+    }
     this.captureVersion++;
     this.camera = void 0;
     if (this.engine) await this.run(() => this.engine.stopVideoCapture());
   }
   async configureVideoEncoding(config) {
     const engine = this.requireEngine();
-    this.requireCamera();
+    this.requireLocalVideo();
+    const size = this.externalVideo ? config : rtcOrientedVideoSize(config);
     await this.run(() => engine.setVideoEncoderConfig({
-      ...rtcOrientedVideoSize({ width: config.width, height: config.height }),
+      width: size.width,
+      height: size.height,
       frameRate: config.frameRate,
       maxKbps: config.maximumBitrate,
       contentHint: config.encoderPreference === "maintainFramerate" /* maintainFramerate */ ? "motion" : "detail",
@@ -2772,7 +3224,7 @@ var VeRtcManager = class {
     await this.recovery?.catch(() => {
     });
     const engine = this.requireEngine();
-    if (config.provider !== "vertc" || config.appID !== VERTC_APP_ID || this.connection) {
+    if (config.provider !== "vertc" /* vertc */ || config.appID !== VERTC_APP_ID || this.connection) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "VeRTC credentials for the configured AppID and an idle room are required");
     }
     this.clearRoom();
@@ -2819,7 +3271,7 @@ var VeRtcManager = class {
     const engine = this.requireEngine();
     const current = this.connection;
     if (signal?.aborted) throw this.cancelled();
-    if (!current || config.provider !== "vertc" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+    if (!current || config.provider !== "vertc" /* vertc */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "VeRTC session binding changed");
     }
     const version = this.roomVersion;
@@ -2861,7 +3313,7 @@ var VeRtcManager = class {
           throw this.cancelled();
         }
       }
-      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.videoRequested && this.camera) {
+      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.videoRequested && (this.camera || this.externalVideo)) {
         await this.run(() => engine.publishStream(this.sdk.MediaType.VIDEO));
         this.ensureCurrent(engine, version);
         if (!this.videoRequested) {
@@ -2869,7 +3321,7 @@ var VeRtcManager = class {
           this.ensureCurrent(engine, version);
         }
       }
-      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.audioRequested && this.microphone) {
+      if ((this.tokenExpired || this.publishPrivilegeExpired) && this.audioRequested && (this.microphone || this.externalAudio)) {
         await this.run(() => engine.publishStream(this.sdk.MediaType.AUDIO));
         this.ensureCurrent(engine, version);
         if (!this.audioRequested) {
@@ -2893,7 +3345,7 @@ var VeRtcManager = class {
   }
   async publishLocalVideo() {
     const engine = this.requireEngine();
-    this.requireCamera();
+    this.requireLocalVideo();
     this.videoRequested = true;
     const version = this.roomVersion;
     await this.recovery;
@@ -2907,12 +3359,15 @@ var VeRtcManager = class {
   }
   async publishLocalAudio() {
     const engine = this.requireEngine();
+    if (this.externalVideo && !this.externalAudio) {
+      return;
+    }
     this.audioRequested = true;
     const version = this.roomVersion;
     await this.recovery;
     this.ensureCurrent(engine, version);
     try {
-      if (!this.microphone) {
+      if (!this.externalVideo && !this.microphone) {
         await engine.startAudioCapture();
         if (!this.isCurrent(engine, version)) {
           await engine.stopAudioCapture().catch(() => {
@@ -2924,7 +3379,7 @@ var VeRtcManager = class {
       if (!this.audioRequested) throw this.cancelled();
       await engine.publishStream(this.sdk.MediaType.AUDIO);
     } catch (error) {
-      throw this.mapError(error, "MICROPHONE_PERMISSION_DENIED" /* microphonePermissionDenied */);
+      throw this.mapError(error, this.externalVideo ? "RTC_ERROR" /* rtcError */ : "MICROPHONE_PERMISSION_DENIED" /* microphonePermissionDenied */);
     }
   }
   async unpublishLocalAudio() {
@@ -3189,6 +3644,15 @@ var VeRtcManager = class {
     if (!this.engine) throw new XmaxError("RTC_ERROR" /* rtcError */, "VeRTC is not initialized");
     return this.engine;
   }
+  /**
+   * 获取已准备的文件或摄像头视频轨。
+   */
+  requireLocalVideo() {
+    if (this.externalVideo) {
+      return this.externalVideo;
+    }
+    return this.requireCamera();
+  }
   requireCamera() {
     if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
     return this.camera;
@@ -3215,12 +3679,14 @@ var VeRtcManager = class {
 // src/Foundation/RTC/RtcFactory.ts
 function createRtcManager(provider, environment) {
   switch (provider) {
+    case "trtc" /* trtc */:
+      return new TrtcRtcManager();
     case "agora" /* agora */:
       return new AgoraRtcManager({ environment });
     case "vertc" /* vertc */:
       return new VeRtcManager();
     default:
-      return new TrtcRtcManager();
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported RTC provider");
   }
 }
 
@@ -3715,91 +4181,548 @@ var _CameraController = class _CameraController {
 __publicField(_CameraController, "localVideoTrackID", "video0");
 var CameraController = _CameraController;
 
-// src/Service/Realtime/RealtimeSession.ts
-var RealtimeSession = class {
-  /**
-   * 创建实时会话。
-   *
-   * @param init.id 会话标识（sessionUid）。
-   * @param init.userID 业务用户标识。
-   * @param init.status 会话状态。
-   * @param init.connection RTC 连接参数。
-   * @param init.closeReason 会话关闭原因。
-   */
-  constructor(init) {
-    /**
-     * 会话信息
-     */
-    /**
-     * 会话标识（sessionUid）。
-     */
-    __publicField(this, "id");
-    /**
-     * 业务用户标识。
-     */
-    __publicField(this, "userID");
-    /**
-     * 运行状态
-     */
-    /**
-     * 会话状态（如 ACTIVE）；响应未携带时为空。
-     */
-    __publicField(this, "status");
-    /**
-     * 会话关闭原因。
-     */
-    __publicField(this, "closeReason");
+// src/Service/Realtime/RealtimeReferenceVideo.ts
+var RealtimeVideoSampleMethod = /* @__PURE__ */ ((RealtimeVideoSampleMethod2) => {
+  RealtimeVideoSampleMethod2["time"] = "time";
+  RealtimeVideoSampleMethod2["fps"] = "fps";
+  return RealtimeVideoSampleMethod2;
+})(RealtimeVideoSampleMethod || {});
+
+// src/Media/Video/NetworkVideoController.ts
+var NetworkVideoController = class {
+  constructor() {
     /**
-     * RTC 连接
+     * 当前视频源与完成通知
      */
+    __publicField(this, "currentTrack");
+    __publicField(this, "reference");
+    __publicField(this, "onFinish");
     /**
-     * RTC 连接参数；心跳等响应未携带完整参数时为空。
+     * 预览进度与视图资源
      */
-    __publicField(this, "connection");
-    this.id = init.id;
-    this.userID = init.userID;
-    this.status = init.status;
-    this.connection = init.connection;
-    this.closeReason = init.closeReason;
+    __publicField(this, "position", 0);
+    __publicField(this, "ended", false);
+    __publicField(this, "bindings", /* @__PURE__ */ new Map());
   }
-};
-
-// src/Foundation/RTC/RoomJoinConfiguration.ts
-var RoomJoinConfiguration = class {
   /**
-   * 创建房间加入参数。
-   *
-   * @param init.roomID TRTC 房间号。
-   * @param init.userID TRTC 登录身份。
-   * @param init.sdkAppID TRTC SDKAppID（字符串形式）。
-   * @param init.userSig TRTC 登录签名。
-   * @param init.privateMapKey TRTC 进房鉴权字段。
+   * 创建网络视频源，校验地址、采样方式和模型支持的尺寸；不请求视频下载。
    */
-  constructor(init) {
-    /**
-     * RTC 提供方。
-     */
-    __publicField(this, "provider", "trtc");
-    /**
-     * 进房参数
-     */
-    /**
-     * TRTC 房间号（字符串房间号）。
-     */
-    __publicField(this, "roomID");
-    /**
-     * TRTC 登录身份（`rtc_user_id`）。
-     */
-    __publicField(this, "userID");
-    /**
-     * TRTC SDKAppID（字符串形式，进房时转换为数值）。
-     */
-    __publicField(this, "sdkAppID");
-    /**
-     * TRTC 登录签名。
-     */
-    __publicField(this, "userSig");
-    /**
+  create(options, mediaService) {
+    let url;
+    try {
+      url = new URL(options.url);
+    } catch {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an absolute HTTP or HTTPS URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an HTTP or HTTPS URL without embedded credentials");
+    }
+    const sampleMethod = options.sampleMethod ?? "time" /* time */;
+    if (!Object.values(RealtimeVideoSampleMethod).includes(sampleMethod)) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported video sample method");
+    }
+    if (this.currentTrack) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current network video stream before creating another one");
+    }
+    options.videoFormat.validate();
+    const size = mediaService.resolveModelInputSize(options.videoFormat);
+    const track = new RealtimeVideoTrack({
+      id: "network-video",
+      videoFormat: options.videoFormat.resized(size.width, size.height)
+    });
+    this.currentTrack = track;
+    this.reference = Object.freeze({ path: options.url.trim(), sampleMethod });
+    this.onFinish = options.onFinish;
+    VideoRenderRegistry.register(track, {
+      attachHandler: (view) => this.attach(view),
+      detachHandler: (view) => this.detach(view)
+    });
+    return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+  }
+  /**
+   * 释放全部预览绑定及源信息，不影响其他媒体源。
+   */
+  stop() {
+    for (const view of this.bindings.keys()) {
+      this.detach(view);
+    }
+    if (this.currentTrack) {
+      VideoRenderRegistry.unregister(this.currentTrack);
+    }
+    this.currentTrack = void 0;
+    this.reference = void 0;
+    this.onFinish = void 0;
+    this.position = 0;
+    this.ended = false;
+  }
+  /**
+   * 绑定播放器，恢复预览位置；本地播放错误仅记录，不中断服务端生成。
+   */
+  attach(view) {
+    if (!this.reference || !view.videoElement || !view.setVideoURL) {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "This render target does not support network video preview");
+    }
+    this.detach(view);
+    const video = view.videoElement;
+    video.autoplay = !this.ended;
+    const restore = () => {
+      if (this.position > 0) {
+        video.currentTime = Math.min(this.position, Math.max(0, video.duration - 1e-3) || this.position);
+      }
+      if (this.ended) {
+        video.pause();
+      }
+    };
+    const fail = () => {
+      XmaxLogger.render.warning(() => "\u7F51\u7EDC\u89C6\u9891\u9884\u89C8\u5931\u8D25 (Network Video Preview Failed)");
+    };
+    video.addEventListener("loadedmetadata", restore);
+    video.addEventListener("error", fail);
+    this.bindings.set(view, () => {
+      this.position = video.currentTime;
+      this.ended = video.ended || this.ended;
+      video.removeEventListener("loadedmetadata", restore);
+      video.removeEventListener("error", fail);
+      view.setVideoURL?.(null);
+    });
+    view.isMirrored = false;
+    view.setVideoURL(this.reference.path);
+  }
+  /**
+   * 保存预览进度并释放该视图的地址和事件监听。
+   */
+  detach(view) {
+    this.bindings.get(view)?.();
+    this.bindings.delete(view);
+  }
+};
+
+// src/Media/Video/LocalVideoController.ts
+var LocalVideoController = class {
+  /**
+   * 保存媒体错误处理器，不创建浏览器资源。
+   */
+  constructor(onError = () => {
+  }) {
+    /**
+     * 当前文件资源与运行期错误通知
+     */
+    __publicField(this, "source");
+    __publicField(this, "onError");
+    this.onError = onError;
+  }
+  /**
+   * 是否持有文件资源，包含尚未完成准备的播放器。
+   */
+  get isActive() {
+    return this.source !== void 0;
+  }
+  /**
+   * 准备完成的本地视频轨。
+   */
+  get currentTrack() {
+    return this.source?.track;
+  }
+  /**
+   * 文件音频输出；禁用音频时为空，无音轨文件的 Web Audio 输出为静音。
+   */
+  get audioTrack() {
+    return this.source?.audioDestination?.stream.getAudioTracks()[0];
+  }
+  /**
+   * 校验文件和格式，准备首帧与音频输出；应从用户点击事件直接调用以解锁播放。
+   */
+  async create(options, mediaService, signal) {
+    if (this.source) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local video before creating another one");
+    }
+    if (!(options.file instanceof Blob) || options.file.size === 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video requires a non-empty File or Blob");
+    }
+    const format = this.resolveVideoFormat(options.videoFormat, mediaService);
+    if (signal.aborted) {
+      throw this.cancelled();
+    }
+    if (typeof document === "undefined") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Local video requires a browser");
+    }
+    const video = document.createElement("video");
+    const canvas = document.createElement("canvas");
+    const context = canvas.getContext("2d");
+    if (!context || typeof canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas video capture is unavailable");
+    }
+    canvas.width = format.width;
+    canvas.height = format.height;
+    const source = {
+      video,
+      canvas,
+      context,
+      url: URL.createObjectURL(options.file),
+      abort: new AbortController(),
+      targets: /* @__PURE__ */ new Set()
+    };
+    this.source = source;
+    try {
+      video.playsInline = true;
+      video.loop = options.loop ?? true;
+      video.preload = "auto";
+      video.volume = 1;
+      video.muted = options.includeAudio === false;
+      if (options.includeAudio !== false) {
+        if (typeof AudioContext === "undefined") {
+          throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Web Audio is unavailable; disable file audio or use a supported browser");
+        }
+        const audio = new AudioContext();
+        source.audioContext = audio;
+        source.audioSource = audio.createMediaElementSource(video);
+        source.audioDestination = audio.createMediaStreamDestination();
+        source.audioSource.connect(source.audioDestination);
+      }
+      video.src = source.url;
+      const resume = source.audioContext?.resume();
+      const playing = this.play(source, signal);
+      await this.wait(source, Promise.all([resume, playing]), signal);
+      video.pause();
+      if (!video.videoWidth || !video.videoHeight || !Number.isFinite(video.duration) || video.duration <= 0) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "The file has no playable finite video stream");
+      }
+      await this.rewind(source, signal);
+      this.draw(source);
+      source.stream = canvas.captureStream(format.fps);
+      const nativeTrack = source.stream.getVideoTracks()[0];
+      if (!nativeTrack) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas did not provide a video track");
+      }
+      const track = new RealtimeVideoTrack({ id: "local-video", videoFormat: format });
+      track.mediaStreamTrack = nativeTrack;
+      source.track = track;
+      this.draw(source);
+      source.drawTimer = setInterval(() => {
+        if (this.source !== source) {
+          return;
+        }
+        try {
+          this.draw(source);
+        } catch {
+          this.handleError(source);
+        }
+      }, 1e3 / format.fps);
+      source.onError = () => this.handleError(source);
+      video.addEventListener("error", source.onError);
+      VideoRenderRegistry.register(track, {
+        attachHandler: (view) => {
+          view.isMirrored = false;
+          view.setMediaStream(source.stream);
+          source.targets.add(view);
+        },
+        detachHandler: (view) => {
+          source.targets.delete(view);
+          view.setMediaStream(null);
+        }
+      });
+      return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+    } catch (error) {
+      await this.stop();
+      throw XmaxError.from(error);
+    }
+  }
+  /**
+   * 开始信令发送成功后，从文件开头同步启动音视频；不等待远端首帧。
+   */
+  async start(signal) {
+    const source = this.source;
+    if (!source?.track) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is not prepared");
+    }
+    if (signal.aborted) {
+      throw this.cancelled();
+    }
+    try {
+      await this.rewind(source, signal);
+      await this.wait(source, Promise.all([source.audioContext?.resume(), this.play(source, signal)]), signal);
+    } catch (error) {
+      source.video.pause();
+      throw error;
+    }
+  }
+  /**
+   * 暂停文件音视频，保留当前预览；重新开始生成时回到文件开头。
+   */
+  pause() {
+    this.source?.video.pause();
+  }
+  /**
+   * 释放播放器、预览、定时器、轨道、音频上下文和对象 URL。
+   */
+  async stop() {
+    const source = this.source;
+    this.source = void 0;
+    if (!source) {
+      return;
+    }
+    source.abort.abort();
+    clearInterval(source.drawTimer);
+    if (source.onError) {
+      source.video.removeEventListener("error", source.onError);
+    }
+    if (source.track) {
+      VideoRenderRegistry.unregister(source.track);
+      source.track.mediaStreamTrack = void 0;
+    }
+    for (const view of source.targets) {
+      try {
+        view.setMediaStream(null);
+      } catch {
+      }
+    }
+    source.targets.clear();
+    source.video.pause();
+    source.video.removeAttribute("src");
+    source.video.load();
+    source.stream?.getTracks().forEach((track) => track.stop());
+    source.audioDestination?.stream.getTracks().forEach((track) => track.stop());
+    source.audioSource?.disconnect();
+    source.audioDestination?.disconnect();
+    URL.revokeObjectURL(source.url);
+    await source.audioContext?.close().catch(() => {
+    });
+  }
+  /**
+   * 播放被浏览器拒绝时给出可操作错误；关闭后的迟到播放立即暂停。
+   */
+  play(source, signal) {
+    return source.video.play().then(() => {
+      if (this.source !== source || source.abort.signal.aborted || signal.aborted) {
+        source.video.pause();
+        throw this.cancelled();
+      }
+    }).catch((error) => {
+      if (error instanceof XmaxError) {
+        throw error;
+      }
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Cannot play local video; call from a user click and use a browser-supported video codec");
+    });
+  }
+  /**
+   * 等待 seek 完成，确保重新生成从首帧开始，而非使用旧缓存画面。
+   */
+  async rewind(source, signal) {
+    if (source.video.currentTime === 0) {
+      return;
+    }
+    let seeked;
+    const ready = new Promise((resolve) => {
+      seeked = resolve;
+    });
+    source.video.addEventListener("seeked", seeked, { once: true });
+    try {
+      source.video.currentTime = 0;
+      await this.wait(source, ready, signal);
+    } finally {
+      source.video.removeEventListener("seeked", seeked);
+    }
+  }
+  /**
+   * 给浏览器准备和播放操作设置 10 秒上限，同时响应关闭、取消和解码错误。
+   */
+  wait(source, operation, signal) {
+    return new Promise((resolve, reject) => {
+      const finish = (error) => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+        source.abort.signal.removeEventListener("abort", abort);
+        source.video.removeEventListener("error", failed);
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+      const abort = () => finish(this.cancelled());
+      const failed = () => finish(new XmaxError("MEDIA_ERROR" /* mediaError */, "The browser cannot decode this video file"));
+      const timer = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Local video preparation timed out; start from a user click and check the video codec")), 1e4);
+      signal.addEventListener("abort", abort, { once: true });
+      source.abort.signal.addEventListener("abort", abort, { once: true });
+      source.video.addEventListener("error", failed, { once: true });
+      operation.then(() => finish(), finish);
+      if (signal.aborted || source.abort.signal.aborted) {
+        abort();
+      }
+    });
+  }
+  /**
+   * 等比缩放并居中补黑边，保留完整画面，不按设备方向转置文件尺寸。
+   */
+  draw(source) {
+    const { video, canvas, context } = source;
+    if (video.readyState < 2) {
+      return;
+    }
+    const scale = Math.min(canvas.width / video.videoWidth, canvas.height / video.videoHeight);
+    const width = video.videoWidth * scale;
+    const height = video.videoHeight * scale;
+    context.fillStyle = "black";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(video, (canvas.width - width) / 2, (canvas.height - height) / 2, width, height);
+  }
+  /**
+   * 仅为本地文件选择最接近宽高比的模型档位；比例距离相同时优先横屏。
+   * 无固定档位时保留公共尺寸解析规则，帧率和显式编码配置不变。
+   */
+  resolveVideoFormat(format, mediaService) {
+    format.validate();
+    const buckets = resolutionBuckets(mediaService.model);
+    let target = buckets.find((size2) => size2.width === format.width && size2.height === format.height);
+    if (!target && buckets.length > 0) {
+      const ratio = format.width / format.height;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      for (const bucket of buckets) {
+        const distance = Math.abs(Math.log(bucket.width / bucket.height / ratio));
+        const tied = Math.abs(distance - bestDistance) < 1e-9;
+        if (distance < bestDistance - 1e-9 || tied && bucket.width >= bucket.height && target && target.width < target.height) {
+          target = bucket;
+          bestDistance = distance;
+        }
+      }
+    }
+    const size = mediaService.resolveModelInputSize(target ?? format);
+    return format.resized(size.width, size.height);
+  }
+  /**
+   * 解码或绘制失败时停止媒体推进，并报告一次运行期错误。
+   */
+  handleError(source) {
+    if (this.source !== source || source.drawTimer === void 0) {
+      return;
+    }
+    clearInterval(source.drawTimer);
+    source.drawTimer = void 0;
+    source.video.pause();
+    XmaxLogger.realtime.warning(() => "\u672C\u5730\u89C6\u9891\u89E3\u7801\u5931\u8D25 (Local Video Decode Failed)");
+    this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "Local video decoding failed"));
+  }
+  /**
+   * 构造统一的媒体操作取消错误。
+   */
+  cancelled() {
+    return new XmaxError("CANCELLED" /* cancelled */, "Local video operation was cancelled");
+  }
+};
+
+// src/Service/Realtime/RealtimeContext.ts
+var RealtimeContext = class {
+  /**
+   * 创建实时生成条件并规范化文本和参考路径。
+   */
+  constructor(init) {
+    /**
+     * 服务端直接读取的网络视频。
+     */
+    __publicField(this, "referenceVideo");
+    /**
+     * 生成条件
+     */
+    /**
+     * 实时生成使用的文本条件。
+     */
+    __publicField(this, "prompt");
+    /**
+     * 已上传参考图片的可选远端路径。
+     */
+    __publicField(this, "referencePath");
+    this.referenceVideo = init.referenceVideo && Object.freeze({ ...init.referenceVideo });
+    this.prompt = init.prompt.trim();
+    const normalizedReferencePath = init.referencePath?.trim();
+    this.referencePath = normalizedReferencePath || void 0;
+  }
+};
+
+// src/Service/Realtime/RealtimeSession.ts
+var RealtimeSession = class {
+  /**
+   * 创建实时会话。
+   *
+   * @param init.id 会话标识（sessionUid）。
+   * @param init.userID 业务用户标识。
+   * @param init.status 会话状态。
+   * @param init.connection RTC 连接参数。
+   * @param init.closeReason 会话关闭原因。
+   */
+  constructor(init) {
+    /**
+     * 会话信息
+     */
+    /**
+     * 会话标识（sessionUid）。
+     */
+    __publicField(this, "id");
+    /**
+     * 业务用户标识。
+     */
+    __publicField(this, "userID");
+    /**
+     * 运行状态
+     */
+    /**
+     * 会话状态（如 ACTIVE）；响应未携带时为空。
+     */
+    __publicField(this, "status");
+    /**
+     * 会话关闭原因。
+     */
+    __publicField(this, "closeReason");
+    /**
+     * RTC 连接
+     */
+    /**
+     * RTC 连接参数；心跳等响应未携带完整参数时为空。
+     */
+    __publicField(this, "connection");
+    this.id = init.id;
+    this.userID = init.userID;
+    this.status = init.status;
+    this.connection = init.connection;
+    this.closeReason = init.closeReason;
+  }
+};
+
+// src/Foundation/RTC/RoomJoinConfiguration.ts
+var RoomJoinConfiguration = class {
+  /**
+   * 创建房间加入参数。
+   *
+   * @param init.roomID TRTC 房间号。
+   * @param init.userID TRTC 登录身份。
+   * @param init.sdkAppID TRTC SDKAppID（字符串形式）。
+   * @param init.userSig TRTC 登录签名。
+   * @param init.privateMapKey TRTC 进房鉴权字段。
+   */
+  constructor(init) {
+    /**
+     * RTC 提供方。
+     */
+    __publicField(this, "provider", "trtc" /* trtc */);
+    /**
+     * 进房参数
+     */
+    /**
+     * TRTC 房间号（字符串房间号）。
+     */
+    __publicField(this, "roomID");
+    /**
+     * TRTC 登录身份（`rtc_user_id`）。
+     */
+    __publicField(this, "userID");
+    /**
+     * TRTC SDKAppID（字符串形式，进房时转换为数值）。
+     */
+    __publicField(this, "sdkAppID");
+    /**
+     * TRTC 登录签名。
+     */
+    __publicField(this, "userSig");
+    /**
      * TRTC 进房鉴权字段（字符串房间号对应的 privateMapKey）。
      */
     __publicField(this, "privateMapKey");
@@ -3872,10 +4795,10 @@ var RealtimeSessionConnection = class {
   }
 };
 function toRoomJoinConfiguration(connection) {
-  return connection.provider === "trtc" ? new RoomJoinConfiguration(connection) : connection;
+  return connection.provider === "trtc" /* trtc */ ? new RoomJoinConfiguration(connection) : connection;
 }
 function connectionAppID(connection) {
-  return connection.provider === "trtc" ? connection.sdkAppID : connection.appID;
+  return connection.provider === "trtc" /* trtc */ ? connection.sdkAppID : connection.appID;
 }
 
 // src/Service/Realtime/RealtimeSessionService.ts
@@ -4090,7 +5013,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
       return void 0;
     }
     return new RealtimeSessionConnection({
-      provider: "trtc",
+      provider: "trtc" /* trtc */,
       roomID,
       sdkAppID,
       userID,
@@ -4234,9 +5157,21 @@ var RoomEvent = class _RoomEvent {
   static start(options) {
     return _RoomEvent.encode({
       event: "start",
-      params: _RoomEvent.generationParameters(options),
+      params: {
+        ..._RoomEvent.generationParameters(options),
+        mirror: options.mirror ?? false,
+        ...options.context.referenceVideo && {
+          ref_video_path: options.context.referenceVideo.path,
+          sample_method: options.context.referenceVideo.sampleMethod,
+          target_size: [
+            options.targetSize?.width ?? options.videoFormat.width,
+            options.targetSize?.height ?? options.videoFormat.height
+          ]
+        }
+      },
       user_id: options.userID,
-      uid: options.taskID
+      uid: options.taskID,
+      ...options.context.referenceVideo && { session_uid: options.taskID }
     });
   }
   /**
@@ -4452,20 +5387,20 @@ var _RoomMessageCodec = class _RoomMessageCodec {
       return parsed;
     }
     const key = `${senderUserID}:${chunk.eventId}`;
-    let record = this.records.get(key);
-    if (!record) {
-      record = { count: chunk.count, parts: /* @__PURE__ */ new Map() };
-      this.records.set(key, record);
+    let record2 = this.records.get(key);
+    if (!record2) {
+      record2 = { count: chunk.count, parts: /* @__PURE__ */ new Map() };
+      this.records.set(key, record2);
       this.evictOverflow();
     }
-    record.parts.set(chunk.index, chunk.data);
-    if (record.parts.size < record.count) {
+    record2.parts.set(chunk.index, chunk.data);
+    if (record2.parts.size < record2.count) {
       return void 0;
     }
     this.records.delete(key);
     const parts = [];
-    for (let index = 0; index < record.count; index += 1) {
-      const part = record.parts.get(index);
+    for (let index = 0; index < record2.count; index += 1) {
+      const part = record2.parts.get(index);
       if (part === void 0) {
         return void 0;
       }
@@ -4495,16 +5430,16 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     if (this.chunkEvent === null || typeof parsed !== "object" || parsed === null) {
       return void 0;
     }
-    const record = parsed;
-    if (record.event !== this.chunkEvent || typeof record.eventId !== "string" || record.eventId.length === 0 || !Number.isInteger(record.index) || !Number.isInteger(record.count) || typeof record.data !== "string") {
+    const record2 = parsed;
+    if (record2.event !== this.chunkEvent || typeof record2.eventId !== "string" || record2.eventId.length === 0 || !Number.isInteger(record2.index) || !Number.isInteger(record2.count) || typeof record2.data !== "string") {
       return void 0;
     }
-    const index = record.index;
-    const count = record.count;
+    const index = record2.index;
+    const count = record2.count;
     if (count < 1 || index < 0 || index >= count) {
       return void 0;
     }
-    return { eventId: record.eventId, index, count, data: record.data };
+    return { eventId: record2.eventId, index, count, data: record2.data };
   }
   /**
    * 淘汰最旧的未完成记录，保持缓存不超过上限。
@@ -4616,9 +5551,9 @@ var RoomController = class {
    *
    * @throws 已有房间未离开、操作失效或进房失败时抛出错误。
    */
-  async join(connection, ensureActive) {
+  async join(connection, ensureActive2) {
     try {
-      ensureActive();
+      ensureActive2();
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -4633,10 +5568,10 @@ var RoomController = class {
     this.heartbeat.stop();
     try {
       if (!this.customCodec) this.codec = new RoomMessageCodec(
-        connection.provider === "vertc" ? null : connection.provider === "agora" ? "__agora_chunk__" : "__trtc_chunk__"
+        connection.provider === "vertc" /* vertc */ ? null : connection.provider === "agora" /* agora */ ? "__agora_chunk__" : "__trtc_chunk__"
       );
       await this.rtcManager.joinRoom(toRoomJoinConfiguration(connection));
-      ensureActive();
+      ensureActive2();
       if (this.state.kind !== "joining" || this.state.operationID !== operationID || this.leaveOperation) {
         throw new XmaxError("CANCELLED" /* cancelled */, "RTC room join was cancelled");
       }
@@ -4677,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,
@@ -4828,6 +5764,7 @@ var _EncodingController = class _EncodingController {
      * 基础层组件
      */
     __publicField(this, "rtcManager");
+    __publicField(this, "lastAppliedConfiguration");
     this.rtcManager = options.rtcManager;
   }
   /**
@@ -4863,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）：流畅优先为最低，画质优先为最高。
@@ -5019,6 +5980,7 @@ var StreamController = class {
      * 运行状态
      */
     __publicField(this, "state", makeInitialState());
+    __publicField(this, "roomListener");
     this.rtcManager = options.rtcManager;
     this.roomController = options.roomController ?? new RoomController({ rtcManager: options.rtcManager });
     this.encodingController = options.encodingController ?? new EncodingController({ rtcManager: options.rtcManager });
@@ -5027,13 +5989,19 @@ var StreamController = class {
     this.remoteStreamListener = options.remoteStreamListener ?? (() => {
     });
     this.generationTimeoutMs = options.generationTimeoutMs ?? 3e4;
+    this.roomController.setListener({
+      onRoomMessage: (sender, message) => {
+        this.handleNetworkVideoCompletion(sender, message);
+        this.roomListener?.onRoomMessage(sender, message);
+      }
+    });
     this.rtcManager.setEventListener({
       onTokenWillExpire: options.onCredentialsRequired,
       onTokenExpired: options.onCredentialsRequired,
       onRoomRejoining: () => this.handleRoomRejoining(),
       onError: (error) => this.errorListener(error),
       onNetworkStatistics: (statistics) => {
-        if (this.state.localVideoPublished) {
+        if (this.state.roomID) {
           this.networkStatisticsListener?.(statistics);
         }
       },
@@ -5101,25 +6069,31 @@ 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 房间并发布本地媒体流。
    *
    * @throws 连接已取消，或 RTC 进房、房间配置与本地流发布失败时抛出错误。
    */
-  async connect(connection, includeLocalAudio, ensureActive, beforePublish) {
+  async connect(connection, includeLocalAudio, ensureActive2, beforePublish, publishLocalMedia = true) {
     this.configureRoom({ roomID: connection.roomID, botID: connection.botID });
-    await this.roomController.join(connection, ensureActive);
-    ensureActive();
+    await this.roomController.join(connection, ensureActive2);
+    ensureActive2();
     XmaxLogger.stream.info(
       () => `RTC \u623F\u95F4\u5DF2\u914D\u7F6E (RTC Room Configured)
 \u2514\u2500 roomID: ${connection.roomID}, botID: ${connection.botID ?? "(\u672A\u8BBE\u7F6E)"}`
     );
-    await beforePublish?.();
-    ensureActive();
-    await this.publishLocalStream(includeLocalAudio);
+    if (publishLocalMedia) {
+      await beforePublish?.();
+      ensureActive2();
+      await this.publishLocalStream(includeLocalAudio);
+    }
   }
   /**
    * 清理生成状态、本地发布和远端订阅，并离开当前 RTC 房间。
@@ -5180,18 +6154,22 @@ var StreamController = class {
       }, this.generationTimeoutMs)
     };
     this.state.generationTaskID = taskID;
+    this.state.networkVideoCompletion = options.context.referenceVideo ? { taskID, finished: false, scheduled: false } : void 0;
     this.state.generationWaiter = waiter;
     void confirmation.catch(() => {
     });
     try {
       const sending = this.roomController.startGeneration({
         taskID,
+        mirror: options.mirror ?? false,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
       });
       const state2 = this.state;
-      const sent = Promise.resolve(sending).then(() => {
+      const sent = Promise.resolve(sending).then(async () => {
+        if (this.state !== state2 || state2.generationTaskID !== taskID) return;
+        await options.onStartSent?.();
         if (this.state !== state2 || state2.generationTaskID !== taskID) return;
         for (const userID of state2.publishedRemoteUserIDs) {
           void this.handleRemoteVideoPublished(userID, true);
@@ -5257,9 +6235,9 @@ var StreamController = class {
    *
    * @throws 操作已取消、房间未就绪或信令发送失败时抛出错误。
    */
-  async changeTargetSize(taskID, targetSize, ensureActive) {
+  async updateDownlinkVideoResolution(taskID, targetSize, ensureActive2) {
     try {
-      await this.roomController.changeTargetSize({ taskID, targetSize, ensureActive });
+      await this.roomController.changeTargetSize({ taskID, targetSize, ensureActive: ensureActive2 });
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -5296,7 +6274,50 @@ var StreamController = class {
    * 设置房间业务消息监听器，传入空值时清除监听器。
    */
   setRoomListener(listener) {
-    this.roomController.setListener(listener);
+    this.roomListener = listener;
+  }
+  /**
+   * 生成状态已提交后登记完成通知，避免快速任务在启动返回前交付完成事件。
+   */
+  activateNetworkVideoCompletion(onFinish) {
+    const completion = this.state.networkVideoCompletion;
+    if (completion) {
+      completion.onFinish = onFinish;
+      this.deliverNetworkVideoCompletion();
+    }
+  }
+  /**
+   * 仅接受当前任务和目标机器人的完成消息；不因完成事件立即退房。
+   */
+  handleNetworkVideoCompletion(sender, message) {
+    const state2 = this.state;
+    const completion = state2.networkVideoCompletion;
+    if (!state2.roomID || !completion || completion.taskID !== state2.generationTaskID || message.event !== "video_stopped" || message.uid !== completion.taskID || !sender || state2.botID && sender !== state2.botID) {
+      return;
+    }
+    completion.finished = true;
+    this.deliverNetworkVideoCompletion();
+  }
+  /**
+   * 异步交付一次完成通知；执行前复核任务，隔离用户回调异常。
+   */
+  deliverNetworkVideoCompletion() {
+    const state2 = this.state;
+    const completion = state2.networkVideoCompletion;
+    if (!completion?.finished || !completion.onFinish || completion.scheduled) {
+      return;
+    }
+    completion.scheduled = true;
+    queueMicrotask(() => {
+      if (this.state !== state2 || state2.generationTaskID !== completion.taskID) {
+        return;
+      }
+      try {
+        void Promise.resolve(completion.onFinish?.()).catch(() => {
+        });
+      } catch {
+      }
+    });
   }
   /**
    * 配置当前房间；已有发布、订阅或生成任务时拒绝重新配置。
@@ -5527,6 +6548,7 @@ var StreamController = class {
     const remoteAudioUserIDs = [...this.state.subscribedRemoteAudioUserIDs];
     this.state.generationTaskID = void 0;
     this.state.generationWaiter = void 0;
+    this.state.networkVideoCompletion = void 0;
     this.state.activeRemoteStream = void 0;
     this.state.subscribedRemoteAudioUserIDs.clear();
     if (waiter) {
@@ -5635,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 */) {
@@ -5737,6 +6948,10 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
   get currentState() {
     return this.state;
   }
+  /** 后台自动调档仅在没有前台操作或清理时申请操作租约。 */
+  get isBusy() {
+    return this.activeOperation !== void 0 || this.termination !== void 0;
+  }
   /**
    * 设置实时状态监听器；设置后立即回放当前状态。
    *
@@ -6078,13 +7293,18 @@ var RealtimeLaunchTimer = class {
    * 开始新的启动周期并清空旧快照，返回记录相机创建完成的一次性回调。
    */
   startCamera() {
+    this.start();
+    return this.measure("cameraMs", this.startedAt);
+  }
+  /**
+   * 开始新的启动周期；非摄像头源不产生相机和发布耗时。
+   */
+  start() {
     this.sequence += 1;
     this.active = true;
     this.startedAt = performance.now();
     this.snapshot = Object.freeze({});
-    const complete = this.measure("cameraMs", this.startedAt);
     this.notify();
-    return complete;
   }
   /**
    * 开始等待用户授权系统媒体权限，返回授权决定时调用的记录函数。
@@ -6208,14 +7428,19 @@ 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 */,
         "Local video stream has no video format"
       );
     }
-    await streamController.setVideoEncoderConfig(videoFormat);
+    const publishLocalMedia = options.publishLocalMedia ?? true;
+    if (publishLocalMedia) {
+      await streamController.updateUplinkVideoFormat(videoFormat);
+      options.ensureCurrent();
+      options.onVideoEncoderConfigured?.();
+    }
     options.ensureCurrent();
     let completePublish;
     await streamController.connect(connection, options.includeLocalAudio, () => {
@@ -6225,8 +7450,9 @@ var XmaxRealtimeConnectionManager = class {
       await options.beforePublish?.();
       completeConnection();
       completePublish = this.dependencies.timing.startPublish();
-    });
+    }, publishLocalMedia);
     options.ensureCurrent();
+    completeConnection();
     completePublish?.();
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
@@ -6275,7 +7501,7 @@ var XmaxRealtimeConnectionManager = class {
   async refreshCredentials() {
     if (this.credentialRefresh) return this.credentialRefresh;
     const current = this.activeSession;
-    if (!current?.connection || current.connection.provider === "trtc") return;
+    if (!current?.connection || current.connection.provider === "trtc" /* trtc */) return;
     const version = this.refreshVersion;
     const operation = (async () => {
       try {
@@ -6360,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;
@@ -6376,14 +7602,6 @@ var XmaxRealtimeConnectionManager = class {
       }
     });
   }
-  /**
-   * 同步远端结果画面的镜像状态：与当前本地摄像头位置保持一致。
-   */
-  updateRemoteMirror() {
-    if (this.remoteTarget) {
-      this.remoteTarget.isMirrored = this.dependencies.isMirrored();
-    }
-  }
   /**
    * 构造当前远端生成结果媒体流。
    */
@@ -6428,7 +7646,7 @@ var XmaxRealtimeConnectionManager = class {
       );
       return;
     }
-    if (next.provider !== "trtc" && (force || !previous || previous.provider === "trtc" || next.roomToken !== previous.roomToken)) {
+    if (next.provider !== "trtc" /* trtc */ && (force || !previous || previous.provider === "trtc" /* trtc */ || next.roomToken !== previous.roomToken)) {
       await this.dependencies.streamController.updateCredentials(next, this.credentialController?.signal);
       if (version !== this.refreshVersion || this.activeSession !== current) return;
     }
@@ -6526,7 +7744,10 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       const confirmation = this.streamController.beginGeneration({
         taskID,
         videoFormat: options.videoFormat,
-        context
+        context,
+        ...options.targetSize && { targetSize: options.targetSize },
+        mirror: options.mirror ?? false,
+        ...options.onStartSent && { onStartSent: options.onStartSent }
       });
       await this.awaitConfirmation(confirmation, options.signal);
       options.ensureCurrent();
@@ -6552,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;
@@ -6659,6 +7881,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     __publicField(this, "coordinator");
     __publicField(this, "errorHandler");
     __publicField(this, "cameraController");
+    __publicField(this, "networkVideoController", new NetworkVideoController());
+    __publicField(this, "localVideoController", new LocalVideoController((error) => {
+      void this.coordinator.terminateWithError(error, 0 /* connection */);
+    }));
+    __publicField(this, "rtcManager");
     /**
      * 启动计时与首帧通知
      */
@@ -6684,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);
     /**
      * 音量配置
      */
@@ -6695,6 +7930,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.supportsInterpolation = dependencies?.supportsFrameInterpolation ?? (async (size) => await frameInterpolationAdapter(size) !== null);
     this.errorHandler = new RealtimeErrorHandler();
     const rtcManager = dependencies?.rtcManager ?? createRtcManager(options.provider, dependencies?.environment ?? "china" /* china */);
+    this.rtcManager = rtcManager;
     this.cameraController = dependencies?.cameraController ?? new CameraController({
       rtcManager,
       mediaService: this.mediaService,
@@ -6721,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);
@@ -6737,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;
@@ -6746,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();
       }
     });
@@ -6773,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.cameraController.currentTrack?.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();
@@ -6785,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();
+    }
+  }
   /**
    * 根据当前视频尺寸准备插帧，能力不可用时降级为原视频，并在应用前校验租约。
    */
@@ -6838,7 +8136,6 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     const size = this.interpolationSize;
     this.connectionManager.setFrameInterpolation(size ? {
       size,
-      targetFrameRate: this.options.frameInterpolation.targetFrameRate,
       onFailure: (error) => {
         if (revision === this.interpolationRevision) this.handleInterpolationFailure(error);
       }
@@ -6945,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;
@@ -6999,6 +8300,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "media" /* media */,
       void 0,
       async (token) => {
+        this.ensureNoLocalSource();
         await this.coordinator.commit(
           new RealtimeState({
             connectionState: "Preparing" /* preparing */
@@ -7035,6 +8337,63 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     );
   }
+  /**
+   * 创建网络视频源并初始化接收端 RTC；预览是否加载成功不影响服务端读取视频。
+   */
+  async createNetworkVideoStream(options) {
+    return this.coordinator.run("media" /* media */, void 0, async (token) => {
+      this.ensureNoLocalSource();
+      const stream = this.networkVideoController.create(options, this.mediaService);
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      await this.rtcManager.initialize();
+      token.ensureCurrent();
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 创建文件音视频源并准备外部轨道；准备失败时统一释放本次媒体和 RTC 资源。
+   */
+  async createLocalVideoStream(options) {
+    return this.coordinator.run("media" /* media */, void 0, async (token) => {
+      this.ensureNoLocalSource();
+      if (!this.rtcManager.setExternalMediaTracks) {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "The RTC provider does not support local video streams");
+      }
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      const stream = await this.localVideoController.create(options, this.mediaService, token.signal);
+      token.ensureCurrent();
+      await this.rtcManager.initialize();
+      token.ensureCurrent();
+      await this.rtcManager.setExternalMediaTracks({
+        videoTrack: stream.videoTrack.mediaStreamTrack,
+        audioTrack: this.localVideoController.audioTrack
+      });
+      token.ensureCurrent();
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 当前 Manager 拥有的媒体源轨道。
+   */
+  get currentLocalTrack() {
+    return this.localVideoController.currentTrack ?? this.networkVideoController.currentTrack ?? this.cameraController.currentTrack;
+  }
+  /**
+   * 创建前拒绝覆盖活动源，避免旧预览或连接资源被静默遗留。
+   */
+  ensureNoLocalSource() {
+    if (this.currentLocalTrack || this.localVideoController.isActive) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local stream before creating another one");
+    }
+  }
   /**
    * 移除媒体权限弹窗观察；授权决定已记录或不再需要观察时调用。
    */
@@ -7046,26 +8405,105 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 应用完整的上行视频格式，成功后更新本地轨道元数据，不改变生成格式或生命周期。
    * 复用配置操作准入，避免与建连、切换摄像头或其他配置更新并发。
    *
-   * @throws 无本地相机流、参数无效、操作冲突或底层编码更新失败时抛错。
+   * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
-  async updateVideoFormat(videoFormat) {
+  async updateUplinkVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const track = this.cameraController.currentTrack;
+      const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
       const previousFormat = track?.videoFormat;
       if (!track || !previousFormat) {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera stream is not started");
+        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;
     });
   }
   /**
    * 停止本地相机流并释放本地预览与 RTC 资源。
    */
   async stopLocalCameraStream() {
+    if (this.networkVideoController.currentTrack || this.localVideoController.isActive) {
+      return;
+    }
     await this.coordinator.run(
       "media" /* media */,
       void 0,
@@ -7096,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;
       }
     );
@@ -7106,11 +8544,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   /**
    * 使用当前 Manager 创建的本地流建立实时连接。
    *
-   * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
+   * 创建实时会话、加入 RTC 房间并启动会话心跳；摄像头源发布本地流，网络视频源仅接收。
    * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
    * 返回的远端媒体流在生成开始后承载远端生成画面。
    *
-   * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+   * @param localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
    * @returns 远端生成结果占位的媒体流。
    * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
    * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -7137,7 +8575,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
    * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
    *
-   * @param options.localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+   * @param options.localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
    * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
    * @returns 承载远端生成画面的媒体流。
    * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
@@ -7149,7 +8587,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       void 0,
       async (token) => {
         const localTrack = options.localStream.videoTrack;
-        if (!localTrack || localTrack !== this.cameraController.currentTrack) {
+        if (!localTrack || localTrack !== this.currentLocalTrack) {
           throw new XmaxError(
             "INVALID_CONFIGURATION" /* invalidConfiguration */,
             "The local stream must be created and started by this realtime manager"
@@ -7166,12 +8604,18 @@ 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();
           return this.connectionManager.makeRemoteStream();
         }
-        const context = this.generationManager.validateContext(options.context);
+        const supplied = this.generationManager.validateContext(options.context);
+        const referenceVideo = this.networkVideoController.reference;
+        if (!referenceVideo && supplied.referenceVideo) {
+          throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Create a network video stream before using a reference video");
+        }
+        const context = referenceVideo ? new RealtimeContext({ ...supplied, referenceVideo }) : supplied;
         if (currentState.connectionState !== "Connected" /* connected */) {
           await this.performConnect(options.localStream, token);
         }
@@ -7183,6 +8627,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 断开实时连接并保留当前本地媒体预览。
    */
   async disconnect() {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     this.clearVideoStatistics();
     await this.coordinator.disconnect();
@@ -7192,10 +8637,20 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 关闭期间重复调用会等待同一个释放任务；关闭完成后仍可重新创建本地流。
    */
   async close() {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     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") };
+  }
   /**
    * 建立实时连接：创建会话、进房发布、启动心跳并准备远端渲染轨道。
    *
@@ -7205,7 +8660,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async performConnect(localStream, token) {
     const localTrack = localStream.videoTrack;
-    if (!localTrack || localTrack !== this.cameraController.currentTrack) {
+    if (!localTrack || localTrack !== this.currentLocalTrack) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
         "The local stream must be created and started by this realtime manager"
@@ -7223,7 +8678,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (token.signal.aborted) abortWarmup();
     try {
       let beforePublish;
-      if (this.cameraController.isFrameValidationEnabled) {
+      if (!this.localVideoController.isActive && !this.networkVideoController.currentTrack && this.cameraController.isFrameValidationEnabled) {
         const cameraReady = this.cameraController.waitForValidCameraFrame(warmupController.signal).then(() => {
           token.ensureCurrent();
         });
@@ -7231,11 +8686,22 @@ 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.cameraController.useMicrophone,
+        includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : !this.networkVideoController.currentTrack && this.cameraController.useMicrophone,
+        publishLocalMedia: !this.networkVideoController.currentTrack,
         ensureCurrent: () => token.ensureCurrent(),
         onPublished: () => {
           this.acceptsVideoStatistics = true;
@@ -7260,16 +8726,25 @@ 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 () => {
+        token.ensureCurrent();
+        await this.localVideoController.start(token.signal);
+        token.ensureCurrent();
+      } : void 0,
       waitUntilRemoteReady: () => this.connectionManager.waitUntilRemoteTrackReady(
         REMOTE_FIRST_FRAME_TIMEOUT_MS,
         token.signal
@@ -7279,10 +8754,26 @@ 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 && (() => {
+        if (this.currentState.taskID === taskID && this.currentState.connectionState === "Generating" /* generating */) {
+          return onFinish();
+        }
+      }));
+    }
     return this.connectionManager.makeRemoteStream();
   }
   /**
@@ -7299,6 +8790,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 统一清理顺序：停止心跳与生成，再断开连接；all 额外释放本地媒体。
    */
   async performCleanup(scope, taskID) {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     this.remoteFrameDisplayHandler = void 0;
     this.clearVideoStatistics();
@@ -7309,20 +8801,30 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     await this.generationManager.reset(taskID);
     const sessionID = await this.connectionManager.disconnect();
     if (scope === 1 /* all */) {
+      const hadFileSource = this.networkVideoController.currentTrack !== void 0 || this.localVideoController.isActive;
+      this.networkVideoController.stop();
       this.generationVideoFormat = void 0;
       this.disposePermissionWatch();
       try {
-        await this.cameraController.stopLocalCameraStream();
+        if (hadFileSource) {
+          await this.rtcManager.destroy();
+        } else {
+          await this.cameraController.stopLocalCameraStream();
+        }
       } catch (error) {
         XmaxLogger.realtime.error(
-          () => `\u505C\u6B62\u672C\u5730\u76F8\u673A\u6D41\u5931\u8D25 (Failed to Stop Local Camera Stream)
+          () => `\u91CA\u653E\u672C\u5730\u5A92\u4F53\u5931\u8D25 (Failed to Release Local Media)
 \u2514\u2500 ${XmaxLogger.localized("\u539F\u56E0\uFF1A", "Reason: ")}${XmaxError.from(error).message}`
         );
+      } finally {
+        if (this.localVideoController.isActive) {
+          await this.localVideoController.stop();
+        }
       }
     }
     return {
       sessionID,
-      hasLocalMedia: this.cameraController.currentTrack !== void 0
+      hasLocalMedia: this.currentLocalTrack !== void 0
     };
   }
   /**
@@ -7338,51 +8840,450 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
 };
 
-// src/Core/XmaxConfiguration.ts
-var XmaxConfiguration = class {
+// src/Core/XmaxConfiguration.ts
+var XmaxConfiguration = class {
+  /**
+   * 创建 SDK 全局配置。
+   *
+   * @param init.apiKey 调用 Xmax 服务使用的 API Key。
+   * @param init.environment SDK 连接的服务环境；默认为国内环境。
+   * @param init.loggerOptions SDK 输出的日志类型；默认为空。
+   */
+  constructor(init) {
+    /**
+     * 服务身份与环境
+     */
+    /**
+     * 调用 Xmax 服务使用的 API Key。
+     */
+    __publicField(this, "apiKey");
+    /**
+     * SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。
+     */
+    __publicField(this, "environment");
+    /**
+     * 日志配置
+     */
+    /**
+     * SDK 输出的日志类型；默认为不输出日志。
+     */
+    __publicField(this, "loggerOptions");
+    this.apiKey = init.apiKey.trim();
+    this.environment = init.environment ?? "china" /* china */;
+    this.loggerOptions = init.loggerOptions ?? 0 /* none */;
+  }
+  /**
+   * 校验全局配置。
+   * @throws API Key 为空时抛出 `XmaxError`。
+   */
+  validate() {
+    if (this.apiKey.length === 0) {
+      throw new XmaxError(
+        "INVALID_API_KEY" /* invalidAPIKey */,
+        "API key cannot be empty"
+      );
+    }
+  }
+};
+
+// src/Service/NonRealtime/NonRealtimeTask.ts
+var NonRealtimeQuality = /* @__PURE__ */ ((NonRealtimeQuality2) => {
+  NonRealtimeQuality2["sd"] = "sd";
+  NonRealtimeQuality2["hd"] = "hd";
+  return NonRealtimeQuality2;
+})(NonRealtimeQuality || {});
+var NonRealtimeTaskStatus = /* @__PURE__ */ ((NonRealtimeTaskStatus2) => {
+  NonRealtimeTaskStatus2["submitted"] = "submitted";
+  NonRealtimeTaskStatus2["processing"] = "processing";
+  NonRealtimeTaskStatus2["completed"] = "completed";
+  NonRealtimeTaskStatus2["error"] = "error";
+  return NonRealtimeTaskStatus2;
+})(NonRealtimeTaskStatus || {});
+
+// src/Service/NonRealtime/NonRealtimeTaskService.ts
+var SUPPORTED_FPS = /* @__PURE__ */ new Set([8, 10, 12, 15, 16, 18, 20, 22, 24, 25, 30, 45, 48, 50, 60, 72, 90, 100, 120]);
+var NonRealtimeTaskService = class {
+  /**
+   * 注入非实时任务使用的 API 服务。
+   */
+  constructor(api) {
+    /**
+     * 网络依赖
+     */
+    __publicField(this, "api");
+    this.api = api;
+  }
+  /**
+   * 提交一次任务；请求结果不确定时也不自动重试，以免重复扣费。
+   */
+  async submitTask(options) {
+    const model = options.model?.trim();
+    if (!model) {
+      invalid("Model must not be empty");
+    }
+    const prompt = options.prompt.trim();
+    if (!prompt || [...prompt].length > 1024) {
+      invalid("Prompt must contain 1\u20131024 characters");
+    }
+    validateURL(options.videoPath);
+    if (options.referencePath !== void 0) {
+      validateURL(options.referencePath);
+    }
+    if (!Object.values(NonRealtimeQuality).includes(options.quality)) {
+      invalid("Quality must be sd or hd");
+    }
+    if (options.fps !== void 0 && !SUPPORTED_FPS.has(options.fps)) {
+      invalid("Unsupported processing frame rate");
+    }
+    const payload = await this.api.post("/offline-task", {
+      model,
+      prompt,
+      refVideoPath: options.videoPath.trim(),
+      ...options.referencePath === void 0 ? {} : { refImagePath: options.referencePath.trim() },
+      quality: options.quality,
+      ...options.fps === void 0 ? {} : { fps: options.fps }
+    });
+    return parseTask(payload);
+  }
+  /**
+   * 查询任务，校验返回 ID；signal 只取消本次 HTTP 查询，不取消服务端任务。
+   */
+  async getTask(taskUid, signal) {
+    const uid = validateTaskUid(taskUid);
+    const task = parseTask(await this.api.get(`/offline-task/${encodeURIComponent(uid)}`, { signal }));
+    if (task.uid !== uid) {
+      malformed("Task UID does not match the request");
+    }
+    return task;
+  }
+  /**
+   * 查询最多 100 个 ID，按首次出现顺序去重；任一任务不可用时整体失败。
+   */
+  async getTasks(taskUids) {
+    if (taskUids.length < 1 || taskUids.length > 100) {
+      invalid("Provide 1\u2013100 task UIDs");
+    }
+    const uids = [...new Set(taskUids.map(validateTaskUid))];
+    const payload = record(await this.api.post("/offline-task/batch-query", { taskUids: uids }));
+    const tasks = parseList(payload.list);
+    if (tasks.length !== uids.length || tasks.some((task, index) => task.uid !== uids[index])) {
+      malformed("Batch response does not match the requested task UIDs");
+    }
+    return tasks;
+  }
+  /**
+   * 分页查询任务，不隐式加载其他页。
+   */
+  async listTasks(options = {}) {
+    const pageNumber = options.pageNumber ?? 1;
+    const pageSize = options.pageSize ?? 10;
+    if (!Number.isSafeInteger(pageNumber) || pageNumber < 1) {
+      invalid("Page number must be a positive integer");
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+      invalid("Page size must be between 1 and 100");
+    }
+    if (options.status !== void 0 && !Object.values(NonRealtimeTaskStatus).includes(options.status)) {
+      invalid("Invalid task status");
+    }
+    const query = new URLSearchParams({ pageNumber: String(pageNumber), pageSize: String(pageSize) });
+    if (options.status !== void 0) {
+      query.set("status", options.status);
+    }
+    const payload = record(await this.api.get(`/offline-task/page?${query}`));
+    return Object.freeze({
+      pageNumber: pageInteger(payload, "pageNumber", 1),
+      pageSize: pageInteger(payload, "pageSize", 1),
+      total: pageInteger(payload, "total", 0),
+      list: parseList(payload.list)
+    });
+  }
+};
+function validateTaskUid(value) {
+  const uid = value.trim();
+  if (!uid || uid === "." || uid === "..") {
+    invalid("Task UID must not be empty or a relative path segment");
+  }
+  return uid;
+}
+function validateURL(value) {
+  let url;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    return invalid("Resource must be an uploaded HTTP(S) URL");
+  }
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) {
+    invalid("Resource must be an uploaded HTTP(S) URL");
+  }
+}
+function invalid(message) {
+  throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, message);
+}
+function malformed(message = "Invalid non-realtime response data") {
+  throw new XmaxError("API_ERROR" /* apiError */, message);
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    malformed();
+  }
+  return value;
+}
+function field(data, key, type) {
+  const value = data[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== type || typeof value === "number" && (!Number.isFinite(value) || value < 0)) {
+    malformed(`Invalid field: ${key}`);
+  }
+  return value;
+}
+function pageInteger(data, key, minimum) {
+  const value = field(data, key, "number");
+  if (value === void 0 || !Number.isSafeInteger(value) || value < minimum) {
+    malformed(`Invalid field: ${key}`);
+  }
+  return value;
+}
+function parseList(value) {
+  if (!Array.isArray(value)) {
+    malformed("Missing task list");
+  }
+  return Object.freeze(value.map(parseTask));
+}
+function parseTask(value) {
+  const data = record(value);
+  const uid = field(data, "uid", "string");
+  const status = field(data, "status", "string");
+  const quality = field(data, "quality", "string");
+  if (!uid?.trim() || !Object.values(NonRealtimeTaskStatus).includes(status)) {
+    malformed("Missing task UID or invalid status");
+  }
+  if (quality !== void 0 && !Object.values(NonRealtimeQuality).includes(quality)) {
+    malformed("Invalid task quality");
+  }
+  return Object.freeze({
+    uid,
+    status,
+    quality,
+    userUid: field(data, "userUid", "string"),
+    prompt: field(data, "prompt", "string"),
+    videoPath: field(data, "refVideoPath", "string"),
+    referencePath: field(data, "refImagePath", "string"),
+    processorId: field(data, "processorId", "string"),
+    requestedFps: field(data, "requestedFps", "number"),
+    resolvedFps: field(data, "resolvedFps", "number"),
+    retryCount: field(data, "retryCount", "number"),
+    videoDurationSeconds: field(data, "videoDurationSeconds", "number"),
+    billableDurationSeconds: field(data, "billableDurationSeconds", "number"),
+    chargePoints: field(data, "chargePoints", "number"),
+    result: data.result == null ? void 0 : parseResult(data.result),
+    processStartTime: field(data, "processStartTime", "string"),
+    createTimestamp: field(data, "createTimestamp", "string"),
+    updateTimestamp: field(data, "updateTimestamp", "string")
+  });
+}
+function parseResult(value) {
+  const data = record(value);
+  return Object.freeze({
+    url: field(data, "result_url", "string"),
+    uploadError: field(data, "upload_error", "string"),
+    uploadStatus: field(data, "upload_status", "string"),
+    finalizeDurationMs: field(data, "finalize_duration_ms", "number"),
+    compressionLevel: field(data, "compression_level", "string"),
+    frameCount: field(data, "frame_count", "number"),
+    fps: field(data, "fps", "number"),
+    durationMs: field(data, "result_duration_ms", "number"),
+    fileSizeBytes: field(data, "file_size_bytes", "number"),
+    droppedFrameCount: field(data, "dropped_frame_count", "number"),
+    originalFileSizeBytes: field(data, "original_file_size_bytes", "number")
+  });
+}
+
+// src/Service/NonRealtime/NonRealtimeTaskError.ts
+var NonRealtimeTaskError = class extends XmaxError {
   /**
-   * 创建 SDK 全局配置。
-   *
-   * @param init.apiKey 调用 Xmax 服务使用的 API Key。
-   * @param init.environment SDK 连接的服务环境；默认为国内环境。
-   * @param init.loggerOptions SDK 输出的日志类型；默认为空。
+   * 使用 API 错误分类，不虚构服务端未返回的业务错误码。
    */
-  constructor(init) {
-    /**
-     * 服务身份与环境
-     */
-    /**
-     * 调用 Xmax 服务使用的 API Key。
-     */
-    __publicField(this, "apiKey");
-    /**
-     * SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。
-     */
-    __publicField(this, "environment");
+  constructor(task, message) {
+    super("API_ERROR" /* apiError */, message);
     /**
-     * 日志配置
+     * 失败上下文
      */
+    __publicField(this, "task");
+    this.name = "NonRealtimeTaskError";
+    this.task = task;
+  }
+};
+
+// src/Core/NonRealtime/XmaxNonRealtimeManager.ts
+var XmaxNonRealtimeManager = class {
+  /**
+   * 注入非实时任务服务。
+   */
+  constructor(tasks) {
     /**
-     * SDK 输出的日志类型；默认为不输出日志。
+     * 服务层组件
      */
-    __publicField(this, "loggerOptions");
-    this.apiKey = init.apiKey.trim();
-    this.environment = init.environment ?? "china" /* china */;
-    this.loggerOptions = init.loggerOptions ?? 0 /* none */;
+    __publicField(this, "tasks");
+    this.tasks = tasks;
   }
   /**
-   * 校验全局配置。
-   * @throws API Key 为空时抛出 `XmaxError`。
+   * 单次提交任务，不自动重试可能已扣费的请求。
    */
-  validate() {
-    if (this.apiKey.length === 0) {
+  submitTask(options) {
+    return this.tasks.submitTask(options);
+  }
+  /**
+   * 取得任务快照，不把服务端失败终态当成查询失败。
+   */
+  getTask(taskUid, options) {
+    return this.tasks.getTask(taskUid, options?.signal);
+  }
+  /**
+   * 批量取得任务快照。
+   */
+  getTasks(taskUids) {
+    return this.tasks.getTasks(taskUids);
+  }
+  /**
+   * 分页取得任务列表。
+   */
+  listTasks(options) {
+    return this.tasks.listTasks(options);
+  }
+  /**
+   * 等待任务完成；查询串行执行，瞬时错误有限退避，取消与总超时覆盖请求及等待阶段。
+   */
+  async waitForCompletion(taskUid, options = {}) {
+    const uid = validateTaskUid(taskUid);
+    const interval = options.intervalMs ?? 2e3;
+    const retries = options.maxConsecutiveRetries ?? 3;
+    validateDelay(interval);
+    if (options.timeoutMs !== void 0) {
+      validateDelay(options.timeoutMs);
+    }
+    if (!Number.isSafeInteger(retries) || retries < 0) {
       throw new XmaxError(
-        "INVALID_API_KEY" /* invalidAPIKey */,
-        "API key cannot be empty"
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        "Retry count must be a non-negative integer"
       );
     }
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort();
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) {
+      abort();
+    }
+    const timer = options.timeoutMs === void 0 ? void 0 : setTimeout(() => {
+      timedOut = true;
+      abort();
+    }, options.timeoutMs);
+    let failures = 0;
+    try {
+      for (; ; ) {
+        ensureActive(controller.signal);
+        let task;
+        try {
+          task = await this.tasks.getTask(uid, controller.signal);
+        } catch (error) {
+          ensureActive(controller.signal);
+          if (!isTransient(error) || failures >= retries) {
+            throw error;
+          }
+          failures++;
+          await delay(Math.min(interval * 2 ** (failures - 1), 3e4), controller.signal);
+          continue;
+        }
+        ensureActive(controller.signal);
+        failures = 0;
+        try {
+          void Promise.resolve(options.onTaskUpdated?.(task)).catch(() => {
+          });
+        } catch {
+        }
+        ensureActive(controller.signal);
+        if (task.status === "error" /* error */) {
+          throw new NonRealtimeTaskError(task, `Non-realtime task ${uid} failed`);
+        }
+        if (task.status === "completed" /* completed */) {
+          if (!isResultAvailable(task)) {
+            throw new NonRealtimeTaskError(
+              task,
+              `Non-realtime task ${uid} completed without a usable result`
+            );
+          }
+          return task;
+        }
+        await delay(interval, controller.signal);
+      }
+    } catch (error) {
+      if (timedOut) {
+        throw new XmaxError(
+          "TIMEOUT" /* timeout */,
+          `Waiting for task ${uid} timed out; the server task was not cancelled`
+        );
+      }
+      ensureActive(controller.signal);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", abort);
+    }
   }
 };
+function validateDelay(value) {
+  if (!Number.isFinite(value) || value <= 0 || value > 2147483647) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Polling durations must be positive and within the timer range");
+  }
+}
+function ensureActive(signal) {
+  if (signal.aborted) {
+    throw new XmaxError(
+      "CANCELLED" /* cancelled */,
+      "Task wait was cancelled locally; the server task was not cancelled"
+    );
+  }
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const finish = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      try {
+        ensureActive(signal);
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    };
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+    if (signal.aborted) {
+      finish();
+    }
+  });
+}
+function isTransient(error) {
+  if (!(error instanceof XmaxError)) {
+    return false;
+  }
+  return error.code === "NETWORK_ERROR" /* networkError */ || error.code === "TIMEOUT" /* timeout */ || error.code === "API_ERROR" /* apiError */ && (error.httpStatus ?? 0) >= 500 && (error.apiCode === void 0 || error.apiCode === error.httpStatus);
+}
+function isResultAvailable(task) {
+  const result = task.result;
+  if (!result?.url?.trim() || result.uploadError?.trim() || result.uploadStatus !== void 0 && result.uploadStatus !== "success") {
+    return false;
+  }
+  try {
+    const url = new URL(result.url);
+    return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
 
 // src/Core/XmaxClient.ts
 var XmaxClient = class {
@@ -7429,6 +9330,17 @@ var XmaxClient = class {
       environment: this.configuration.environment
     });
   }
+  /**
+   * 创建非实时视频任务 Manager，使用全局 API Key 和当前环境的非实时任务服务地址。
+   * 本方法不发起网络请求或加载 RTC，任务由服务端持久化，可按 ID 恢复查询。
+   */
+  createNonRealtimeManager() {
+    const apiService = new ApiService({
+      apiKey: this.configuration.apiKey,
+      baseURL: nonRealtimeApiBaseURL(this.configuration.environment)
+    });
+    return new XmaxNonRealtimeManager(new NonRealtimeTaskService(apiService));
+  }
   /**
    * 创建媒体处理与能力查询 Service。
    *
@@ -7440,7 +9352,7 @@ var XmaxClient = class {
   /**
    * 创建文件存储 Service。
    *
-   * @returns 可上传图片到对象存储的存储 Service，返回地址可用作参考图路径。
+   * @returns 可上传图片和视频到对象存储的存储 Service。
    */
   createStorageService() {
     return new StorageService({ apiService: this.apiService });
@@ -7452,45 +9364,36 @@ var RealtimeConfiguration = class {
   /**
    * 创建实时业务配置。
    *
-   * @param init.model 实时生成业务使用的模型。
-   * @param init.provider RTC 提供方，默认 TRTC；创建后不可切换。
-   * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
-   * @param init.frameInterpolation 插帧开关和显示帧率上限的详细配置。
+   * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1-preview。
+   * @param init.provider RTC 提供方，默认按模型定义选择；必须受模型支持，创建后不可切换。
+   * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧，默认 false。
    */
   constructor(init) {
-    /**
-     * RTC 配置
-     */
-    __publicField(this, "provider");
-    /**
-     * 模型配置
-     */
     /**
      * 实时生成业务使用的模型。
      */
     __publicField(this, "model");
     /**
-     * 远端插帧配置
+     * 实时连接使用的 RTC 提供方。
      */
+    __publicField(this, "provider");
     /**
      * 是否默认请求开启远端生成画面的插帧。
      */
     __publicField(this, "isFrameInterpolationEnabled");
-    /**
-     * 已补全默认值的只读插帧配置。
-     */
-    __publicField(this, "frameInterpolation");
-    this.provider = init.provider ?? "trtc" /* trtc */;
+    const providers = supportedRtcProviders(init.model);
+    this.provider = init.provider ?? providers[0];
     if (!Object.values(RtcProvider).includes(this.provider)) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported RTC provider");
     }
-    this.model = init.model;
-    const targetFrameRate = init.frameInterpolation?.targetFrameRate ?? 60;
-    if (!Number.isFinite(targetFrameRate) || targetFrameRate < 1 || targetFrameRate > 60) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Interpolation targetFrameRate must be between 1 and 60");
+    if (!providers.includes(this.provider)) {
+      throw new XmaxError(
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        `Model ${init.model} does not support RTC provider ${this.provider}`
+      );
     }
-    this.isFrameInterpolationEnabled = init.frameInterpolation?.enabled ?? init.isFrameInterpolationEnabled ?? false;
-    this.frameInterpolation = Object.freeze({ enabled: this.isFrameInterpolationEnabled, targetFrameRate });
+    this.model = init.model;
+    this.isFrameInterpolationEnabled = init.isFrameInterpolationEnabled ?? false;
   }
 };
 
@@ -7501,26 +9404,143 @@ var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
   return VideoContentMode2;
 })(VideoContentMode || {});
 
-// src/Service/Realtime/RealtimeContext.ts
-var RealtimeContext = class {
+// src/Render/Video/RenderStatisticsController.ts
+var RenderStatisticsController = class {
   /**
-   * 创建实时生成条件并规范化文本和参考路径。
+   * 绑定用于观察原视频帧的元素，调用 start 后才开始采集。
    */
-  constructor(init) {
+  constructor(video) {
+    __publicField(this, "video", video);
     /**
-     * 生成条件
+     * 统计回调
      */
+    __publicField(this, "handler");
     /**
-     * 实时生成使用的文本条件。
+     * 帧观察与采样生命周期
      */
-    __publicField(this, "prompt");
+    __publicField(this, "timer");
+    __publicField(this, "callbackID");
+    __publicField(this, "sequence", 0);
     /**
-     * 已上传参考图片的可选远端路径。
+     * 采样窗口与输出方式
      */
-    __publicField(this, "referencePath");
-    this.prompt = init.prompt.trim();
-    const normalizedReferencePath = init.referencePath?.trim();
-    this.referencePath = normalizedReferencePath || void 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 {
+    }
   }
 };
 
@@ -9516,11 +11536,11 @@ var _FrameInterpolationManager = class _FrameInterpolationManager {
     });
   }
   static async create(canvas, size, onFailure, signal) {
-    const ensureActive = () => {
+    const ensureActive2 = () => {
       if (signal.aborted) throw new XmaxError("CANCELLED" /* cancelled */, "Interpolation initialization cancelled");
     };
     const adapter = await frameInterpolationAdapter(size);
-    ensureActive();
+    ensureActive2();
     if (!adapter) throw new XmaxError("FRAME_INTERPOLATION_UNSUPPORTED" /* frameInterpolationUnsupported */, "WebGPU shader-f16 is unavailable");
     const device = await adapter.requestDevice({ requiredFeatures: ["shader-f16"] });
     const manager = new _FrameInterpolationManager(device, canvas, size, onFailure);
@@ -9531,9 +11551,9 @@ var _FrameInterpolationManager = class _FrameInterpolationManager {
       if (!manager.destroyed) onFailure(new Error(`Interpolation GPU device lost: ${info.message}`));
     });
     try {
-      ensureActive();
+      ensureActive2();
       await manager.initialize();
-      ensureActive();
+      ensureActive2();
       return manager;
     } catch (error) {
       manager.destroy();
@@ -9659,6 +11679,7 @@ __publicField(_FrameInterpolationManager, "originalSlots", 3);
 var FrameInterpolationManager = _FrameInterpolationManager;
 
 // src/Render/Video/RemoteVideoFramePipeline.ts
+var INTERPOLATION_FRAME_RATE = 60;
 var RemoteVideoFramePipeline = class {
   constructor(video, canvas, options, createProcessor = FrameInterpolationManager.create) {
     __publicField(this, "video", video);
@@ -9686,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;
@@ -9732,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;
@@ -9753,9 +11778,27 @@ var RemoteVideoFramePipeline = class {
     this.delay = interval;
     this.enqueue({ slot, time });
     this.startTick();
-    if (!consecutive || interval < 2e3 / this.options.targetFrameRate - 1 || previousSlot === void 0 || this.busy) return;
+    if (!consecutive || interval < 2e3 / INTERPOLATION_FRAME_RATE - 1 || previousSlot === void 0 || this.busy) {
+      return;
+    }
     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);
@@ -9782,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);
     });
@@ -9802,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;
@@ -9831,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;
@@ -9914,6 +11962,10 @@ var XmaxVideoView = class {
     __publicField(this, "interpolationOptions");
     __publicField(this, "interpolationPipeline");
     __publicField(this, "interpolationCanvas");
+    /**
+     * 呈现统计组件
+     */
+    __publicField(this, "statisticsController");
     /**
      * DOM 挂载状态
      */
@@ -9924,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;
@@ -9940,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();
+  }
   /**
    * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
    */
@@ -9992,14 +12059,15 @@ var XmaxVideoView = class {
   attach(to) {
     this.detached = false;
     to.appendChild(this.element);
-    if (this.videoElement.srcObject && this.videoElement.paused && typeof this.videoElement.play === "function") {
+    if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && this.videoElement.autoplay && !this.videoElement.ended && this.videoElement.paused && typeof this.videoElement.play === "function") {
       void this.videoElement.play().catch((error) => {
         XmaxLogger.render.warning(() => `\u6062\u590D\u89C6\u9891\u64AD\u653E\u5931\u8D25 (Failed to Resume Video Playback)
 \u2514\u2500 ${String(error)}`);
       });
     }
     this.startInterpolation();
-    if (this.videoElement.srcObject && !this.hasNotifiedFrameDisplay) {
+    this.startRenderStatistics();
+    if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
       this.armFrameDisplayNotification();
     }
   }
@@ -10008,10 +12076,34 @@ var XmaxVideoView = class {
    */
   detach() {
     this.detached = true;
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
+    if (this.videoElement.getAttribute("src")) {
+      this.videoElement.pause();
+    }
     this.element.remove();
   }
+  /**
+   * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
+   */
+  setVideoURL(url) {
+    this.statisticsController.stop();
+    this.stopInterpolation();
+    this.cancelFrameDisplayNotification();
+    this.hasNotifiedFrameDisplay = false;
+    this.videoElement.pause();
+    this.videoElement.srcObject = null;
+    this.videoElement.removeAttribute("src");
+    this.videoElement.muted = true;
+    this.videoElement.loop = false;
+    if (url) {
+      this.videoElement.src = url;
+      this.armFrameDisplayNotification();
+    }
+    this.videoElement.load();
+    this.startRenderStatistics();
+  }
   /**
    * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
    */
@@ -10019,13 +12111,16 @@ var XmaxVideoView = class {
     if (this.videoElement.srcObject === stream) {
       return;
     }
+    this.statisticsController.stop();
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
     this.hasNotifiedFrameDisplay = false;
     this.videoElement.srcObject = stream;
     if (stream) {
+      this.videoElement.autoplay = true;
       this.armFrameDisplayNotification();
       this.startInterpolation();
+      this.startRenderStatistics();
     }
   }
   /**
@@ -10055,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();
   }
@@ -10090,6 +12196,7 @@ var XmaxVideoView = class {
    * 解绑当前轨道并清空渲染内容。
    */
   detachCurrentTrack() {
+    this.statisticsController.stop();
     const track = this.currentTrack;
     if (track) {
       VideoRenderRegistry.binding(track)?.detachHandler(this);
@@ -10097,6 +12204,9 @@ var XmaxVideoView = class {
     this.setFrameInterpolation(void 0);
     this.cancelFrameDisplayNotification();
     this.videoElement.srcObject = null;
+    if (this.videoElement.getAttribute("src")) {
+      this.setVideoURL(null);
+    }
   }
   /**
    * 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。
@@ -10152,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
@@ -10324,25 +12440,31 @@ export {
   XmaxError,
   RealtimeVideoEncoderPreference,
   RealtimeVideoFormat,
+  RtcProvider,
   RealtimeModel,
+  modelDisplayName,
   defaultFrameRate,
   defaultCameraVideoFormat,
+  supportedRtcProviders,
   MediaService,
   StoredFile,
   StorageService,
   CameraPosition,
-  RtcProvider,
   RealtimeVideoTrack,
   RealtimeMediaStream,
+  RealtimeVideoSampleMethod,
+  RealtimeContext,
   RealtimeConnectionState,
   RealtimeReason,
   RealtimeState,
   XmaxConfiguration,
+  NonRealtimeQuality,
+  NonRealtimeTaskStatus,
+  NonRealtimeTaskError,
   XmaxClient,
   RealtimeConfiguration,
   VideoContentMode,
-  RealtimeContext,
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-FMAQXPTE.js.map
+//# sourceMappingURL=chunk-PLFWPS5A.js.map