@xmaxai/web-sdk 1.0.4 → 1.0.5

package/dist/{chunk-FEL5MJMJ.cjs → chunk-JN6HURTT.cjs}

@@ -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.5";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -268,8 +275,24 @@ var _ApiService = class _ApiService {
    */
   async request(method, path, body, options) {
     this.validateConfiguration();
+    if (_optionalChain([options, 'optionalAccess', _4 => _4.signal, 'optionalAccess', _5 => _5.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 });
+    _optionalChain([options, 'optionalAccess', _6 => _6.signal, 'optionalAccess', _7 => _7.addEventListener, 'call', _8 => _8("abort", abortCaller, { once: true })]);
+    request.init.signal = controller.signal;
+    if (timeoutSignal.aborted) {
+      abortTimeout();
+    }
+    if (_optionalChain([options, 'optionalAccess', _9 => _9.signal, 'optionalAccess', _10 => _10.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);
+      _optionalChain([options, 'optionalAccess', _11 => _11.signal, 'optionalAccess', _12 => _12.removeEventListener, 'call', _13 => _13("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 请求。
@@ -388,7 +414,7 @@ var _ApiService = class _ApiService {
         },
         body: encodedBody,
         signal: AbortSignal.timeout(this.timeoutMs),
-        ..._optionalChain([options, 'optionalAccess', _4 => _4.keepalive]) ? { keepalive: true } : {}
+        ..._optionalChain([options, 'optionalAccess', _14 => _14.keepalive]) ? { keepalive: true } : {}
       }
     };
   }
@@ -405,8 +431,9 @@ var _ApiService = class _ApiService {
       });
     }
     const ok = status >= 200 && status < 300;
-    if (!ok || envelope.success !== true) {
-      const message = _optionalChain([envelope, 'access', _5 => _5.message, 'optionalAccess', _6 => _6.trim, 'call', _7 => _7()]);
+    const succeeded = envelope.success === true || envelope.success === void 0 && envelope.code === 200;
+    if (!ok || !succeeded) {
+      const message = _optionalChain([envelope, 'access', _15 => _15.message, 'optionalAccess', _16 => _16.trim, 'call', _17 => _17()]);
       throw new XmaxError(
         "API_ERROR" /* apiError */,
         message || "Xmax API request failed",
@@ -561,6 +588,14 @@ 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";
@@ -569,12 +604,28 @@ var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   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.0-agora" /* x2_0_agora */]: "X2.1-preview-agora",
+  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-vertc"
+};
 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"
 };
 var RESOLUTION_BUCKETS = {
-  ["x2.1-preview" /* x2_1_preview */]: [
+  ["x2.0" /* x2_0 */]: [],
+  ["x2.0-trtc" /* x2_0_trtc */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
   ],
@@ -582,29 +633,31 @@ var RESOLUTION_BUCKETS = {
     { 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.0-agora" /* x2_0_agora */]: 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 +666,24 @@ 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.0-agora" /* x2_0_agora */]: Object.freeze(["agora" /* agora */]),
+  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["vertc" /* vertc */])
+};
+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) {
@@ -625,7 +691,7 @@ async function frameInterpolationAdapter(size) {
   if (size && (!Number.isSafeInteger(size.width) || !Number.isSafeInteger(size.height) || size.width <= 0 || size.height <= 0)) return null;
   try {
     const adapter = await navigator.gpu.requestAdapter();
-    if (!_optionalChain([adapter, 'optionalAccess', _8 => _8.features, 'access', _9 => _9.has, 'call', _10 => _10("shader-f16")])) return null;
+    if (!_optionalChain([adapter, 'optionalAccess', _18 => _18.features, 'access', _19 => _19.has, 'call', _20 => _20("shader-f16")])) return null;
     if (size && (Math.ceil(size.width / 16) * 16 > adapter.limits.maxTextureDimension2D || Math.ceil(size.height / 16) * 16 > adapter.limits.maxTextureDimension2D)) return null;
     return adapter;
   } catch (e5) {
@@ -802,7 +868,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,15 +909,90 @@ 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 (e6) {
+      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 (_optionalChain([options, 'access', _21 => _21.signal, 'optionalAccess', _22 => _22.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 (_optionalChain([options, 'access', _23 => _23.signal, 'optionalAccess', _24 => _24.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 (_optionalChain([options, 'access', _25 => _25.signal, 'optionalAccess', _26 => _26.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 {
+      _optionalChain([link, 'optionalAccess', _27 => _27.remove, 'call', _28 => _28()]);
+      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);
-      const contentType = _optionalChain([options, 'access', _11 => _11.contentType, 'optionalAccess', _12 => _12.trim, 'call', _13 => _13()]) || _StorageService.inferContentType(safeName);
+      const contentType = _optionalChain([options, 'access', _29 => _29.contentType, 'optionalAccess', _30 => _30.trim, 'call', _31 => _31()]) || _StorageService.inferContentType(safeName);
       const body = _StorageService.makeBody(options.data, contentType);
       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();
@@ -861,7 +1009,7 @@ var StorageService = class _StorageService {
         Key: objectKey,
         Body: body,
         ContentType: contentType,
-        onProgress: options.onProgress ? (info) => _optionalChain([options, 'access', _14 => _14.onProgress, 'optionalCall', _15 => _15(info.loaded, info.total)]) : void 0
+        onProgress: options.onProgress ? (info) => _optionalChain([options, 'access', _32 => _32.onProgress, 'optionalCall', _33 => _33(info.loaded, info.total)]) : void 0
       });
       const url = _StorageService.resolveObjectURL(
         uploaded.Location,
@@ -893,9 +1041,9 @@ var StorageService = class _StorageService {
     const bucket = _StorageService.nonEmpty(payload.bucket);
     const region = _StorageService.nonEmpty(payload.region);
     const prefix = _StorageService.nonEmpty(payload.prefix);
-    const accessKeyID = _StorageService.nonEmpty(_optionalChain([payload, 'access', _16 => _16.credentials, 'optionalAccess', _17 => _17.accessKeyId]));
-    const secretAccessKey = _StorageService.nonEmpty(_optionalChain([payload, 'access', _18 => _18.credentials, 'optionalAccess', _19 => _19.secretAccessKey]));
-    const sessionToken = _StorageService.nonEmpty(_optionalChain([payload, 'access', _20 => _20.credentials, 'optionalAccess', _21 => _21.sessionToken]));
+    const accessKeyID = _StorageService.nonEmpty(_optionalChain([payload, 'access', _34 => _34.credentials, 'optionalAccess', _35 => _35.accessKeyId]));
+    const secretAccessKey = _StorageService.nonEmpty(_optionalChain([payload, 'access', _36 => _36.credentials, 'optionalAccess', _37 => _37.secretAccessKey]));
+    const sessionToken = _StorageService.nonEmpty(_optionalChain([payload, 'access', _38 => _38.credentials, 'optionalAccess', _39 => _39.sessionToken]));
     if (!bucket || !region || !prefix || !accessKeyID || !secretAccessKey || !sessionToken) {
       throw new XmaxError("API_ERROR" /* apiError */, message);
     }
@@ -936,7 +1084,7 @@ var StorageService = class _StorageService {
           reject(
             new XmaxError(
               "UPLOAD_ERROR" /* uploadError */,
-              _optionalChain([error, 'access', _22 => _22.message, 'optionalAccess', _23 => _23.trim, 'call', _24 => _24()]) || "Storage upload failed"
+              _optionalChain([error, 'access', _40 => _40.message, 'optionalAccess', _41 => _41.trim, 'call', _42 => _42()]) || "Storage upload failed"
             )
           );
           return;
@@ -950,14 +1098,14 @@ var StorageService = class _StorageService {
    * 其次拼接自定义 endpoint，最后回退到默认 COS 域名。
    */
   static resolveObjectURL(location, configuration, objectKey) {
-    const candidate = _nullishCoalesce(_optionalChain([location, 'optionalAccess', _25 => _25.trim, 'call', _26 => _26()]), () => ( ""));
+    const candidate = _nullishCoalesce(_optionalChain([location, 'optionalAccess', _43 => _43.trim, 'call', _44 => _44()]), () => ( ""));
     if (candidate.startsWith("//")) {
       return `https:${candidate}`;
     }
     if (/^https?:\/\//i.test(candidate)) {
       return candidate;
     }
-    const endpoint = _optionalChain([configuration, 'access', _27 => _27.endpoint, 'optionalAccess', _28 => _28.trim, 'call', _29 => _29()]);
+    const endpoint = _optionalChain([configuration, 'access', _45 => _45.endpoint, 'optionalAccess', _46 => _46.trim, 'call', _47 => _47()]);
     if (endpoint) {
       const normalized = /^https?:\/\//i.test(endpoint) ? endpoint : `https://${endpoint}`;
       return `${normalized.replace(/\/+$/, "")}/${objectKey}`;
@@ -982,7 +1130,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;
@@ -991,7 +1139,7 @@ var StorageService = class _StorageService {
    * 按文件名后缀推断内容类型。
    */
   static inferContentType(fileName) {
-    const extension = _nullishCoalesce(_optionalChain([fileName, 'access', _30 => _30.split, 'call', _31 => _31("."), 'access', _32 => _32.pop, 'call', _33 => _33(), 'optionalAccess', _34 => _34.toLowerCase, 'call', _35 => _35()]), () => ( ""));
+    const extension = _nullishCoalesce(_optionalChain([fileName, 'access', _48 => _48.split, 'call', _49 => _49("."), 'access', _50 => _50.pop, 'call', _51 => _51(), 'optionalAccess', _52 => _52.toLowerCase, 'call', _53 => _53()]), () => ( ""));
     return _nullishCoalesce(CONTENT_TYPES[extension], () => ( "application/octet-stream"));
   }
   /**
@@ -1010,7 +1158,7 @@ var StorageService = class _StorageService {
    * 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。
    */
   static nonEmpty(value) {
-    const normalized = _optionalChain([value, 'optionalAccess', _36 => _36.trim, 'call', _37 => _37()]);
+    const normalized = _optionalChain([value, 'optionalAccess', _54 => _54.trim, 'call', _55 => _55()]);
     return normalized || void 0;
   }
 };
@@ -1025,7 +1173,7 @@ var CameraPosition = /* @__PURE__ */ ((CameraPosition3) => {
 // src/Foundation/Permissions/MediaPermissionWatch.ts
 var PERMISSION_POLL_INTERVAL_MS = 100;
 async function watchMediaPermissionPrompt(includeMicrophone) {
-  if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _38 => _38.permissions, 'optionalAccess', _39 => _39.query])) {
+  if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _56 => _56.permissions, 'optionalAccess', _57 => _57.query])) {
     return void 0;
   }
   const names = ["camera", ...includeMicrophone ? ["microphone"] : []];
@@ -1044,7 +1192,7 @@ async function watchMediaPermissionPrompt(includeMicrophone) {
           name
         });
         return status.state;
-      } catch (e6) {
+      } catch (e7) {
         return "prompt";
       }
     })
@@ -1052,7 +1200,7 @@ async function watchMediaPermissionPrompt(includeMicrophone) {
   let states;
   try {
     states = await queryOnce();
-  } catch (e7) {
+  } catch (e8) {
     return void 0;
   }
   if (states.every((state2) => state2 === "granted")) {
@@ -1108,12 +1256,12 @@ var AgoraRtcStatistics = class _AgoraRtcStatistics {
       frameRate: valid(stats.receiveFrameRate),
       bitrateKbps: valid(stats.receiveBitrate / 1e3),
       rttMs: valid(rtc.RTT),
-      uplinkLossPercent: _optionalChain([localVideo, 'optionalAccess', _40 => _40.uplinkLossPercent]),
+      uplinkLossPercent: _optionalChain([localVideo, 'optionalAccess', _58 => _58.uplinkLossPercent]),
       downlinkLossPercent: loss(stats.currentPacketLossRate),
       endToEndDelayMs: valid(stats.end2EndDelay)
     }));
-    _optionalChain([listener, 'optionalAccess', _41 => _41.onLocalVideoStatistics, 'optionalCall', _42 => _42(localVideo && Object.freeze(localVideo))]);
-    _optionalChain([listener, 'optionalAccess', _43 => _43.onRemoteVideoStatistics, 'optionalCall', _44 => _44(Object.freeze(remote.map((item) => Object.freeze(item))))]);
+    _optionalChain([listener, 'optionalAccess', _59 => _59.onLocalVideoStatistics, 'optionalCall', _60 => _60(localVideo && Object.freeze(localVideo))]);
+    _optionalChain([listener, 'optionalAccess', _61 => _61.onRemoteVideoStatistics, 'optionalCall', _62 => _62(Object.freeze(remote.map((item) => Object.freeze(item))))]);
     XmaxLogger.rtc.info(() => `Agora \u8FD0\u884C\u7EDF\u8BA1 (Agora RTC Statistics)
 ${JSON.stringify({
       rttMs: valid(rtc.RTT),
@@ -1131,7 +1279,7 @@ ${JSON.stringify({
   static network(stats, listener) {
     const quality = (value) => Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
     const result = Object.freeze({ uplinkQuality: quality(stats.uplinkNetworkQuality), downlinkQuality: quality(stats.downlinkNetworkQuality) });
-    _optionalChain([listener, 'optionalAccess', _45 => _45.onNetworkStatistics, 'optionalCall', _46 => _46(result)]);
+    _optionalChain([listener, 'optionalAccess', _63 => _63.onNetworkStatistics, 'optionalCall', _64 => _64(result)]);
     XmaxLogger.rtc.info(() => `Agora \u7F51\u7EDC\u8D28\u91CF (Agora Network Quality)
 ${JSON.stringify(result, null, 2)}`, 2 /* performance */);
   }
@@ -1151,17 +1299,17 @@ ${JSON.stringify(result, null, 2)}`, 2 /* performance */);
 
 // src/Foundation/RTC/RtcVideoOrientation.ts
 function shouldTransposeRtcVideoSize(environment) {
-  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _47 => _47.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
-  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _48 => _48.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
+  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _65 => _65.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
+  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _66 => _66.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
   const mobile = /Android|webOS|iPhone|iPad|iPod|Mobile/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
   if (!mobile) {
     return false;
   }
-  const orientationType = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _49 => _49.orientationType]), () => ( (typeof window === "undefined" ? void 0 : _optionalChain([window, 'access', _50 => _50.screen, 'optionalAccess', _51 => _51.orientation, 'optionalAccess', _52 => _52.type]))));
+  const orientationType = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _67 => _67.orientationType]), () => ( (typeof window === "undefined" ? void 0 : _optionalChain([window, 'access', _68 => _68.screen, 'optionalAccess', _69 => _69.orientation, 'optionalAccess', _70 => _70.type]))));
   if (orientationType !== void 0) {
     return orientationType.includes("portrait");
   }
-  const degrees = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _53 => _53.orientationDegrees]), () => ( (typeof window === "undefined" ? void 0 : window.orientation)));
+  const degrees = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _71 => _71.orientationDegrees]), () => ( (typeof window === "undefined" ? void 0 : window.orientation)));
   return degrees === 0 || degrees === 180;
 }
 function rtcOrientedVideoSize(size, environment) {
@@ -1185,6 +1333,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __publicField(this, "lifecycle", 0);
     __publicField(this, "camera");
     __publicField(this, "microphone");
+    __publicField(this, "externalVideo");
+    __publicField(this, "externalAudio");
     __publicField(this, "connection");
     __publicField(this, "roomVersion", 0);
     /**
@@ -1256,7 +1406,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (typeof client.sendStreamMessage !== "function") {
       throw new XmaxError("RTC_ERROR" /* rtcError */, "Agora DataStream is unavailable in this SDK version");
     }
-    _AgoraRtcManager.regions.set(sdk, { environment: this.environment, count: (_nullishCoalesce(_optionalChain([region, 'optionalAccess', _54 => _54.count]), () => ( 0))) + 1 });
+    _AgoraRtcManager.regions.set(sdk, { environment: this.environment, count: (_nullishCoalesce(_optionalChain([region, 'optionalAccess', _72 => _72.count]), () => ( 0))) + 1 });
     this.sdk = sdk;
     this.client = client;
     this.registerEvents(client);
@@ -1267,19 +1417,22 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async destroy() {
     this.lifecycle++;
     const client = this.client;
-    this.listener = void 0;
     this.clearRoom();
     this.client = void 0;
-    _optionalChain([client, 'optionalAccess', _55 => _55.removeAllListeners, 'call', _56 => _56()]);
-    _optionalChain([this, 'access', _57 => _57.camera, 'optionalAccess', _58 => _58.close, 'call', _59 => _59()]);
-    _optionalChain([this, 'access', _60 => _60.microphone, 'optionalAccess', _61 => _61.close, 'call', _62 => _62()]);
+    _optionalChain([client, 'optionalAccess', _73 => _73.removeAllListeners, 'call', _74 => _74()]);
+    _optionalChain([this, 'access', _75 => _75.camera, 'optionalAccess', _76 => _76.close, 'call', _77 => _77()]);
+    _optionalChain([this, 'access', _78 => _78.microphone, 'optionalAccess', _79 => _79.close, 'call', _80 => _80()]);
+    _optionalChain([this, 'access', _81 => _81.externalVideo, 'optionalAccess', _82 => _82.close, 'call', _83 => _83()]);
+    _optionalChain([this, 'access', _84 => _84.externalAudio, 'optionalAccess', _85 => _85.close, 'call', _86 => _86()]);
+    this.externalVideo = void 0;
+    this.externalAudio = void 0;
     this.camera = void 0;
     this.microphone = void 0;
     const sdk = this.sdk;
     this.sdk = void 0;
     try {
-      await _optionalChain([client, 'optionalAccess', _63 => _63.leave, 'call', _64 => _64()]);
-    } catch (e8) {
+      await _optionalChain([client, 'optionalAccess', _87 => _87.leave, 'call', _88 => _88()]);
+    } catch (e9) {
       XmaxLogger.rtc.warning(() => "Agora \u9000\u623F\u5931\u8D25\uFF0C\u5DF2\u91CA\u653E\u672C\u5730\u8D44\u6E90 (Agora Leave Failed)");
     } finally {
       const region = sdk && _AgoraRtcManager.regions.get(sdk);
@@ -1291,7 +1444,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({
@@ -1323,14 +1478,45 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async stopCameraCapture() {
     const camera = this.camera;
     this.camera = void 0;
-    _optionalChain([camera, 'optionalAccess', _65 => _65.close, 'call', _66 => _66()]);
+    _optionalChain([camera, 'optionalAccess', _89 => _89.close, 'call', _90 => _90()]);
   }
   /**
-   * 应用公共编码配置，补偿移动端竖屏的宽高转置。
+   * 将外部原生轨包装为 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 = _optionalChain([tracks, 'access', _91 => _91.audioTrack, 'optionalAccess', _92 => _92.clone, 'call', _93 => _93()]);
+      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) {
+      _optionalChain([wrappedVideo, 'optionalAccess', _94 => _94.close, 'call', _95 => _95()]);
+      _optionalChain([wrappedAudio, 'optionalAccess', _96 => _96.close, 'call', _97 => _97()]);
+      video.stop();
+      _optionalChain([audio, 'optionalAccess', _98 => _98.stop, 'call', _99 => _99()]);
+      throw this.mapError(error);
+    }
+  }
+  /**
+   * 应用公共编码配置；仅相机源补偿移动端转置，Canvas 外部源使用原始方向。
    */
   async configureVideoEncoding(config) {
-    const camera = this.requireCamera();
-    const encodingSize = rtcOrientedVideoSize(config);
+    const camera = this.requireLocalVideo();
+    const encodingSize = this.externalVideo ? config : rtcOrientedVideoSize(config);
     await this.run(async () => {
       await camera.setEncoderConfiguration({
         width: encodingSize.width,
@@ -1346,10 +1532,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 使用会话下发的字符串频道与 UID 入房；不采信后端区域覆盖。
    */
   async joinRoom(configuration) {
-    await _optionalChain([this, 'access', _67 => _67.rejoinTask, 'optionalAccess', _68 => _68.catch, 'call', _69 => _69(() => {
+    await _optionalChain([this, 'access', _100 => _100.rejoinTask, 'optionalAccess', _101 => _101.catch, 'call', _102 => _102(() => {
     })]);
     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;
@@ -1360,13 +1546,13 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     }
     this.connection = configuration;
     for (const user of client.remoteUsers) {
-      if (user.hasVideo) _optionalChain([this, 'access', _70 => _70.listener, 'optionalAccess', _71 => _71.onRemoteVideoPublished, 'call', _72 => _72(String(user.uid), true)]);
+      if (user.hasVideo) _optionalChain([this, 'access', _103 => _103.listener, 'optionalAccess', _104 => _104.onRemoteVideoPublished, 'call', _105 => _105(String(user.uid), true)]);
     }
     this.statisticsTimer = setInterval(() => {
       if (this.client !== client || !this.connection || this.tokenExpired || this.rejoinOperation) return;
       try {
         AgoraRtcStatistics.collect(client, this.listener);
-      } catch (e9) {
+      } catch (e10) {
         XmaxLogger.rtc.warning(() => "Agora \u7EDF\u8BA1\u91C7\u6837\u5931\u8D25 (Agora Statistics Failed)");
       }
     }, 2e3);
@@ -1382,10 +1568,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 应用同一频道的新 Token；即将过期时续签，已经过期时重新进房并恢复媒体。
    */
   async updateCredentials(config, signal) {
-    if (_optionalChain([signal, 'optionalAccess', _73 => _73.aborted])) throw this.cancelled();
+    if (_optionalChain([signal, 'optionalAccess', _106 => _106.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;
@@ -1398,7 +1584,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       }
     }
     this.ensureRoomCurrent(client, version);
-    if (_optionalChain([signal, 'optionalAccess', _74 => _74.aborted])) throw this.cancelled();
+    if (_optionalChain([signal, 'optionalAccess', _107 => _107.aborted])) throw this.cancelled();
     if (this.tokenExpired) await this.rejoinRoom(client, config, signal);
     else this.connection = config;
   }
@@ -1421,21 +1607,21 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         reject(this.cancelled());
       };
       this.cancelRejoin = cancel;
-      _optionalChain([signal, 'optionalAccess', _75 => _75.addEventListener, 'call', _76 => _76("abort", cancel, { once: true })]);
+      _optionalChain([signal, 'optionalAccess', _108 => _108.addEventListener, 'call', _109 => _109("abort", cancel, { once: true })]);
       task.then(resolve, reject);
-      if (_optionalChain([signal, 'optionalAccess', _77 => _77.aborted])) cancel();
+      if (_optionalChain([signal, 'optionalAccess', _110 => _110.aborted])) cancel();
     });
     this.rejoinOperation = operation;
     try {
       await operation;
     } finally {
-      _optionalChain([signal, 'optionalAccess', _78 => _78.removeEventListener, 'call', _79 => _79("abort", cancel)]);
+      _optionalChain([signal, 'optionalAccess', _111 => _111.removeEventListener, 'call', _112 => _112("abort", cancel)]);
       if (this.cancelRejoin === cancel) this.cancelRejoin = void 0;
       if (this.rejoinOperation === operation) this.rejoinOperation = void 0;
     }
     this.ensureRoomCurrent(client, version);
     for (const user of client.remoteUsers) {
-      if (user.hasVideo) _optionalChain([this, 'access', _80 => _80.listener, 'optionalAccess', _81 => _81.onRemoteVideoPublished, 'call', _82 => _82(String(user.uid), true)]);
+      if (user.hasVideo) _optionalChain([this, 'access', _113 => _113.listener, 'optionalAccess', _114 => _114.onRemoteVideoPublished, 'call', _115 => _115(String(user.uid), true)]);
     }
   }
   /**
@@ -1443,10 +1629,10 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async performRejoin(client, config, version) {
     this.ensureRoomCurrent(client, version);
-    _optionalChain([this, 'access', _83 => _83.cancelSendDelay, 'optionalCall', _84 => _84()]);
-    _optionalChain([this, 'access', _85 => _85.cancelActiveSend, 'optionalCall', _86 => _86()]);
-    _optionalChain([this, 'access', _87 => _87.listener, 'optionalAccess', _88 => _88.onRoomRejoining, 'optionalCall', _89 => _89()]);
-    for (const user of client.remoteUsers) _optionalChain([user, 'access', _90 => _90.audioTrack, 'optionalAccess', _91 => _91.stop, 'call', _92 => _92()]);
+    _optionalChain([this, 'access', _116 => _116.cancelSendDelay, 'optionalCall', _117 => _117()]);
+    _optionalChain([this, 'access', _118 => _118.cancelActiveSend, 'optionalCall', _119 => _119()]);
+    _optionalChain([this, 'access', _120 => _120.listener, 'optionalAccess', _121 => _121.onRoomRejoining, 'optionalCall', _122 => _122()]);
+    for (const user of client.remoteUsers) _optionalChain([user, 'access', _123 => _123.audioTrack, 'optionalAccess', _124 => _124.stop, 'call', _125 => _125()]);
     await this.run(() => client.leave());
     this.ensureRoomCurrent(client, version);
     await this.run(() => client.join(config.appID, config.roomID, config.roomToken, config.userID));
@@ -1454,12 +1640,14 @@ 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 = _nullishCoalesce(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 (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,7 +1668,7 @@ 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();
@@ -1493,10 +1681,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 = _nullishCoalesce(this.externalVideo, () => ( this.camera));
+    if (this.client && video) {
+      await this.run(() => this.client.unpublish(video));
+    }
   }
   /**
-   * 首次发布时申请麦克风；取消后的迟到采集立即释放。
+   * 外部源只发布提供的音轨；相机源首次发布时申请麦克风，迟到采集立即释放。
    */
   async publishLocalAudio() {
     const client = this.requireClient();
@@ -1504,6 +1695,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 +1722,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));
+    }
   }
   /**
    * 订阅远端主视频并返回原生轨道，不创建额外播放视图。
@@ -1553,8 +1754,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const user = client.remoteUsers.find((user2) => String(user2.uid) === userID);
     if (!subscribe) {
       this.requestedAudio.delete(userID);
-      _optionalChain([user, 'optionalAccess', _93 => _93.audioTrack, 'optionalAccess', _94 => _94.stop, 'call', _95 => _95()]);
-      if (_optionalChain([user, 'optionalAccess', _96 => _96.audioTrack]) && !this.rejoinTask) await this.run(() => client.unsubscribe(user, "audio"));
+      _optionalChain([user, 'optionalAccess', _126 => _126.audioTrack, 'optionalAccess', _127 => _127.stop, 'call', _128 => _128()]);
+      if (_optionalChain([user, 'optionalAccess', _129 => _129.audioTrack]) && !this.rejoinTask) await this.run(() => client.unsubscribe(user, "audio"));
       return;
     }
     this.requestedAudio.add(userID);
@@ -1565,7 +1766,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       if (this.requestedAudio.has(userID)) await this.subscribeRemoteAudio(userID, true);
       return;
     }
-    if (!_optionalChain([user, 'optionalAccess', _97 => _97.hasAudio])) return;
+    if (!_optionalChain([user, 'optionalAccess', _130 => _130.hasAudio])) return;
     const version = this.roomVersion;
     const track = await this.run(() => client.subscribe(user, "audio"));
     if (client !== this.client || version !== this.roomVersion || !this.requestedAudio.has(userID)) {
@@ -1579,9 +1780,9 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   setRemoteAudioVolume(volume, userID) {
     this.audioVolumes.set(userID, Math.max(0, Math.min(100, Number.isFinite(volume) ? Math.round(volume) : 0)));
-    const user = _optionalChain([this, 'access', _98 => _98.client, 'optionalAccess', _99 => _99.remoteUsers, 'access', _100 => _100.find, 'call', _101 => _101((user2) => String(user2.uid) === userID)]);
+    const user = _optionalChain([this, 'access', _131 => _131.client, 'optionalAccess', _132 => _132.remoteUsers, 'access', _133 => _133.find, 'call', _134 => _134((user2) => String(user2.uid) === userID)]);
     if (this.rejoinTask || this.tokenExpired) {
-      _optionalChain([user, 'optionalAccess', _102 => _102.audioTrack, 'optionalAccess', _103 => _103.stop, 'call', _104 => _104()]);
+      _optionalChain([user, 'optionalAccess', _135 => _135.audioTrack, 'optionalAccess', _136 => _136.stop, 'call', _137 => _137()]);
       return;
     }
     if (user) this.applyAudioVolume(user);
@@ -1670,33 +1871,33 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     const handleExpired = () => {
       if (!active() || this.tokenExpired) return;
       this.tokenExpired = true;
-      _optionalChain([this, 'access', _105 => _105.listener, 'optionalAccess', _106 => _106.onTokenExpired, 'optionalCall', _107 => _107()]);
+      _optionalChain([this, 'access', _138 => _138.listener, 'optionalAccess', _139 => _139.onTokenExpired, 'optionalCall', _140 => _140()]);
     };
     client.on("user-published", (user, kind) => {
       if (!mediaActive()) return;
-      if (kind === "video") _optionalChain([this, 'access', _108 => _108.listener, 'optionalAccess', _109 => _109.onRemoteVideoPublished, 'call', _110 => _110(String(user.uid), true)]);
+      if (kind === "video") _optionalChain([this, 'access', _141 => _141.listener, 'optionalAccess', _142 => _142.onRemoteVideoPublished, 'call', _143 => _143(String(user.uid), true)]);
       if (kind === "audio" && this.requestedAudio.has(String(user.uid))) {
         void this.subscribeRemoteAudio(String(user.uid), true).catch((error) => {
-          if (active()) _optionalChain([this, 'access', _111 => _111.listener, 'optionalAccess', _112 => _112.onError, 'optionalCall', _113 => _113(this.mapError(error))]);
+          if (active()) _optionalChain([this, 'access', _144 => _144.listener, 'optionalAccess', _145 => _145.onError, 'optionalCall', _146 => _146(this.mapError(error))]);
         });
       }
     });
     client.on("user-unpublished", (user, kind) => {
       if (!mediaActive()) return;
-      if (kind === "video") _optionalChain([this, 'access', _114 => _114.listener, 'optionalAccess', _115 => _115.onRemoteVideoPublished, 'call', _116 => _116(String(user.uid), false)]);
-      if (kind === "audio") _optionalChain([user, 'access', _117 => _117.audioTrack, 'optionalAccess', _118 => _118.stop, 'call', _119 => _119()]);
+      if (kind === "video") _optionalChain([this, 'access', _147 => _147.listener, 'optionalAccess', _148 => _148.onRemoteVideoPublished, 'call', _149 => _149(String(user.uid), false)]);
+      if (kind === "audio") _optionalChain([user, 'access', _150 => _150.audioTrack, 'optionalAccess', _151 => _151.stop, 'call', _152 => _152()]);
     });
     client.on("user-left", (user) => {
-      if (mediaActive()) _optionalChain([this, 'access', _120 => _120.listener, 'optionalAccess', _121 => _121.onRemoteVideoPublished, 'call', _122 => _122(String(user.uid), false)]);
+      if (mediaActive()) _optionalChain([this, 'access', _153 => _153.listener, 'optionalAccess', _154 => _154.onRemoteVideoPublished, 'call', _155 => _155(String(user.uid), false)]);
     });
     client.on("stream-message", (uid, data) => {
-      if (mediaActive()) _optionalChain([this, 'access', _123 => _123.listener, 'optionalAccess', _124 => _124.onCustomMessageReceived, 'call', _125 => _125(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data))]);
+      if (mediaActive()) _optionalChain([this, 'access', _156 => _156.listener, 'optionalAccess', _157 => _157.onCustomMessageReceived, 'call', _158 => _158(String(uid), typeof data === "string" ? data : new TextDecoder().decode(data))]);
     });
     client.on("network-quality", (quality) => {
       if (mediaActive()) AgoraRtcStatistics.network(quality, this.listener);
     });
     client.on("token-privilege-will-expire", () => {
-      if (active() && !this.tokenExpired) _optionalChain([this, 'access', _126 => _126.listener, 'optionalAccess', _127 => _127.onTokenWillExpire, 'optionalCall', _128 => _128()]);
+      if (active() && !this.tokenExpired) _optionalChain([this, 'access', _159 => _159.listener, 'optionalAccess', _160 => _160.onTokenWillExpire, 'optionalCall', _161 => _161()]);
     });
     client.on("token-privilege-did-expire", handleExpired);
     client.on("connection-state-change", (state2, previous, reason) => {
@@ -1705,7 +1906,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         return;
       }
       if (active() && !this.tokenExpired && state2 === "DISCONNECTED" && previous !== "DISCONNECTED") {
-        _optionalChain([this, 'access', _129 => _129.listener, 'optionalAccess', _130 => _130.onError, 'optionalCall', _131 => _131(new XmaxError("RTC_ERROR" /* rtcError */, `Agora connection disconnected: ${_nullishCoalesce(reason, () => ( "unknown"))}`))]);
+        _optionalChain([this, 'access', _162 => _162.listener, 'optionalAccess', _163 => _163.onError, 'optionalCall', _164 => _164(new XmaxError("RTC_ERROR" /* rtcError */, `Agora connection disconnected: ${_nullishCoalesce(reason, () => ( "unknown"))}`))]);
       }
     });
   }
@@ -1714,20 +1915,20 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   clearRoom() {
     this.roomVersion++;
-    _optionalChain([this, 'access', _132 => _132.cancelRejoin, 'optionalCall', _133 => _133()]);
+    _optionalChain([this, 'access', _165 => _165.cancelRejoin, 'optionalCall', _166 => _166()]);
     this.connection = void 0;
     this.tokenExpired = false;
     this.videoPublishRequested = false;
     this.audioPublishRequested = false;
     clearInterval(this.statisticsTimer);
     this.statisticsTimer = void 0;
-    _optionalChain([this, 'access', _134 => _134.cancelSendDelay, 'optionalCall', _135 => _135()]);
-    _optionalChain([this, 'access', _136 => _136.cancelActiveSend, 'optionalCall', _137 => _137()]);
+    _optionalChain([this, 'access', _167 => _167.cancelSendDelay, 'optionalCall', _168 => _168()]);
+    _optionalChain([this, 'access', _169 => _169.cancelActiveSend, 'optionalCall', _170 => _170()]);
     this.sentPackets = [];
     this.sendTail = Promise.resolve();
     this.requestedAudio.clear();
     this.audioVolumes.clear();
-    for (const user of _nullishCoalesce(_optionalChain([this, 'access', _138 => _138.client, 'optionalAccess', _139 => _139.remoteUsers]), () => ( []))) _optionalChain([user, 'access', _140 => _140.audioTrack, 'optionalAccess', _141 => _141.stop, 'call', _142 => _142()]);
+    for (const user of _nullishCoalesce(_optionalChain([this, 'access', _171 => _171.client, 'optionalAccess', _172 => _172.remoteUsers]), () => ( []))) _optionalChain([user, 'access', _173 => _173.audioTrack, 'optionalAccess', _174 => _174.stop, 'call', _175 => _175()]);
   }
   /**
    * 判断异步恢复工作是否仍属于当前房间生命周期。
@@ -1755,6 +1956,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 = _nullishCoalesce(this.externalVideo, () => ( this.camera));
+    if (!video) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video source is not prepared");
+    }
+    return video;
+  }
   /**
    * 执行声网操作并统一错误类型。
    */
@@ -1787,14 +1998,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 {
   /**
@@ -1863,13 +2066,13 @@ var _RtcEngineManager = class _RtcEngineManager {
    * 释放有效租约、销毁 Engine，并把独占权交给下一个等待者。
    */
   release(lease) {
-    if (_optionalChain([this, 'access', _143 => _143.activeLease, 'optionalAccess', _144 => _144.id]) !== lease.id) {
+    if (_optionalChain([this, 'access', _176 => _176.activeLease, 'optionalAccess', _177 => _177.id]) !== lease.id) {
       return;
     }
     this.activeLease = void 0;
     try {
       lease.engine.destroy();
-    } catch (e10) {
+    } catch (e11) {
     }
     void this.fulfillNextRequest();
   }
@@ -1937,10 +2140,10 @@ var RtcStatsLogger = class {
         `${XmaxLogger.localized("\u7D2F\u8BA1\u63A5\u6536\uFF1A", "Bytes Received: ")}${this.value(stats.bytesReceived, "bytes")}`
       ])];
       const local = stats.localStatistics;
-      if (_optionalChain([local, 'optionalAccess', _145 => _145.audio])) {
+      if (_optionalChain([local, 'optionalAccess', _178 => _178.audio])) {
         blocks.push(this.audioBlock("\u672C\u5730\u97F3\u9891\u53D1\u9001 (Local Audio Uplink)", local.audio, false));
       }
-      for (const video of _nullishCoalesce(_optionalChain([local, 'optionalAccess', _146 => _146.video]), () => ( []))) {
+      for (const video of _nullishCoalesce(_optionalChain([local, 'optionalAccess', _179 => _179.video]), () => ( []))) {
         blocks.push(this.videoBlock("\u672C\u5730\u89C6\u9891\u53D1\u9001 (Local Video Uplink)", video, false));
       }
       for (const remote of _nullishCoalesce(stats.remoteStatistics, () => ( []))) {
@@ -2030,8 +2233,8 @@ var RtcStatsLogger = class {
 
 // src/Foundation/RTC/TRTC/TrtcAudioVolumeSupport.ts
 function canControlTrtcRemoteAudioVolume(environment) {
-  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _147 => _147.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
-  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _148 => _148.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
+  const userAgent = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _180 => _180.userAgent]), () => ( (typeof navigator === "undefined" ? "" : navigator.userAgent)));
+  const maxTouchPoints = _nullishCoalesce(_optionalChain([environment, 'optionalAccess', _181 => _181.maxTouchPoints]), () => ( (typeof navigator === "undefined" ? 0 : _nullishCoalesce(navigator.maxTouchPoints, () => ( 0)))));
   const ios = /iPhone|iPad|iPod/i.test(userAgent) || /Macintosh/i.test(userAgent) && maxTouchPoints > 1;
   return !ios;
 }
@@ -2072,6 +2275,11 @@ var TrtcRtcManager = class {
      */
     __publicField(this, "isCapturing", false);
     __publicField(this, "isAudioCapturing", false);
+    /**
+     * 外部媒体的克隆轨；原始轨道由媒体源管理。
+     */
+    __publicField(this, "externalVideo");
+    __publicField(this, "externalAudio");
     /**
      * 房间状态
      */
@@ -2106,25 +2314,78 @@ 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;
-    _optionalChain([this, 'access', _149 => _149.removeStatsListeners, 'optionalCall', _150 => _150()]);
+    _optionalChain([this, 'access', _182 => _182.removeStatsListeners, 'optionalCall', _183 => _183()]);
     this.removeStatsListeners = void 0;
     if (!lease) {
+      _optionalChain([externalVideo, 'optionalAccess', _184 => _184.stop, 'call', _185 => _185()]);
+      _optionalChain([externalAudio, 'optionalAccess', _186 => _186.stop, 'call', _187 => _187()]);
       return;
     }
     try {
       await lease.engine.stopLocalAudio();
-    } catch (e11) {
+    } catch (e12) {
     }
     try {
       await lease.engine.stopLocalVideo();
-    } catch (e12) {
+    } catch (e13) {
     }
+    _optionalChain([externalVideo, 'optionalAccess', _188 => _188.stop, 'call', _189 => _189()]);
+    _optionalChain([externalAudio, 'optionalAccess', _190 => _190.stop, 'call', _191 => _191()]);
     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 = _optionalChain([tracks, 'access', _192 => _192.audioTrack, 'optionalAccess', _193 => _193.clone, 'call', _194 => _194()]);
+      this.externalAudio = audio;
+      await engine.startLocalVideo({ publish: false, option: { videoTrack: video } });
+      if (_optionalChain([this, 'access', _195 => _195.lease, 'optionalAccess', _196 => _196.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 (_optionalChain([this, 'access', _197 => _197.lease, 'optionalAccess', _198 => _198.engine]) !== engine) {
+          throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
+        }
+      }
+    } catch (error) {
+      if (_optionalChain([this, 'access', _199 => _199.lease, 'optionalAccess', _200 => _200.engine]) === engine) {
+        await engine.stopLocalAudio().catch(() => {
+        });
+        await engine.stopLocalVideo().catch(() => {
+        });
+      }
+      if (this.externalVideo === video) {
+        this.externalVideo = void 0;
+        this.externalAudio = void 0;
+      }
+      video.stop();
+      _optionalChain([audio, 'optionalAccess', _201 => _201.stop, 'call', _202 => _202()]);
+      throw this.mapError(error);
+    }
+  }
   /**
    * 启动摄像头采集（不发布）。
    *
@@ -2133,7 +2394,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,7 +2464,10 @@ var TrtcRtcManager = class {
    * 停止摄像头采集；引擎未初始化或采集未启动时不产生效果。
    */
   async stopCameraCapture() {
-    const engine = _optionalChain([this, 'access', _151 => _151.lease, 'optionalAccess', _152 => _152.engine]);
+    if (this.externalVideo) {
+      return;
+    }
+    const engine = _optionalChain([this, 'access', _203 => _203.lease, 'optionalAccess', _204 => _204.engine]);
     this.isCapturing = false;
     if (!engine) {
       return;
@@ -2220,7 +2484,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();
@@ -2256,7 +2520,7 @@ var TrtcRtcManager = class {
    * 离开当前 RTC 房间；未在房间中或引擎未初始化时不产生效果，退房失败仅记录日志。
    */
   async leaveRoom() {
-    const engine = _optionalChain([this, 'access', _153 => _153.lease, 'optionalAccess', _154 => _154.engine]);
+    const engine = _optionalChain([this, 'access', _205 => _205.lease, 'optionalAccess', _206 => _206.engine]);
     if (!engine || !this.isInRoom) {
       return;
     }
@@ -2276,18 +2540,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 +2573,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 {
@@ -2329,8 +2593,8 @@ var TrtcRtcManager = class {
    * 停止发布本地视频流；采集保持运行，本地预览不受影响。
    */
   async unpublishLocalVideo() {
-    const engine = _optionalChain([this, 'access', _155 => _155.lease, 'optionalAccess', _156 => _156.engine]);
-    if (!engine || !this.isCapturing) {
+    const engine = _optionalChain([this, 'access', _207 => _207.lease, 'optionalAccess', _208 => _208.engine]);
+    if (!engine || !this.isCapturing && !this.externalVideo) {
       return;
     }
     try {
@@ -2340,14 +2604,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 {
@@ -2361,8 +2629,8 @@ var TrtcRtcManager = class {
    * 停止发布本地音频流；麦克风采集保持运行。
    */
   async unpublishLocalAudio() {
-    const engine = _optionalChain([this, 'access', _157 => _157.lease, 'optionalAccess', _158 => _158.engine]);
-    if (!engine || !this.isAudioCapturing) {
+    const engine = _optionalChain([this, 'access', _209 => _209.lease, 'optionalAccess', _210 => _210.engine]);
+    if (!engine || !this.isAudioCapturing && !this.externalAudio) {
       return;
     }
     try {
@@ -2487,19 +2755,19 @@ var TrtcRtcManager = class {
   registerEventBridge(engine) {
     const source = engine;
     const onStatistics = (stats) => {
-      if (this.isInRoom && _optionalChain([this, 'access', _159 => _159.lease, 'optionalAccess', _160 => _160.engine]) === engine) {
+      if (this.isInRoom && _optionalChain([this, 'access', _211 => _211.lease, 'optionalAccess', _212 => _212.engine]) === engine) {
         RtcStatsLogger.logStatistics(stats);
-        const video = _optionalChain([stats, 'access', _161 => _161.localStatistics, 'optionalAccess', _162 => _162.video, 'optionalAccess', _163 => _163.find, 'call', _164 => _164((item) => item.videoType === "big")]);
+        const video = _optionalChain([stats, 'access', _213 => _213.localStatistics, 'optionalAccess', _214 => _214.video, 'optionalAccess', _215 => _215.find, 'call', _216 => _216((item) => item.videoType === "big")]);
         const valid = (value, minimum) => typeof value === "number" && Number.isFinite(value) && value >= minimum ? value : void 0;
-        _optionalChain([this, 'access', _165 => _165.eventListener, 'optionalAccess', _166 => _166.onLocalVideoStatistics, 'optionalCall', _167 => _167(video ? Object.freeze({
+        _optionalChain([this, 'access', _217 => _217.eventListener, 'optionalAccess', _218 => _218.onLocalVideoStatistics, 'optionalCall', _219 => _219(video ? Object.freeze({
           width: valid(video.width, 1),
           height: valid(video.height, 1),
           frameRate: valid(video.frameRate, 0),
           bitrateKbps: valid(video.bitrate, 0)
         }) : void 0)]);
-        _optionalChain([this, 'access', _168 => _168.eventListener, 'optionalAccess', _169 => _169.onRemoteVideoStatistics, 'optionalCall', _170 => _170(Object.freeze(
+        _optionalChain([this, 'access', _220 => _220.eventListener, 'optionalAccess', _221 => _221.onRemoteVideoStatistics, 'optionalCall', _222 => _222(Object.freeze(
           (_nullishCoalesce(stats.remoteStatistics, () => ( []))).flatMap((remote) => {
-            const video2 = _optionalChain([remote, 'access', _171 => _171.video, 'optionalAccess', _172 => _172.find, 'call', _173 => _173((item) => item.videoType === "big")]);
+            const video2 = _optionalChain([remote, 'access', _223 => _223.video, 'optionalAccess', _224 => _224.find, 'call', _225 => _225((item) => item.videoType === "big")]);
             if (!video2) {
               return [];
             }
@@ -2521,11 +2789,11 @@ var TrtcRtcManager = class {
       }
     };
     const onNetworkQuality = (stats) => {
-      if (this.isInRoom && _optionalChain([this, 'access', _174 => _174.lease, 'optionalAccess', _175 => _175.engine]) === engine) {
+      if (this.isInRoom && _optionalChain([this, 'access', _226 => _226.lease, 'optionalAccess', _227 => _227.engine]) === engine) {
         RtcStatsLogger.logNetworkQuality(stats);
         const quality = (value) => Number.isInteger(value) && value >= 0 && value <= 6 ? value : void 0;
         const rtt = (value) => Number.isFinite(value) && value >= 0 ? value : void 0;
-        _optionalChain([this, 'access', _176 => _176.eventListener, 'optionalAccess', _177 => _177.onNetworkStatistics, 'optionalCall', _178 => _178(Object.freeze({
+        _optionalChain([this, 'access', _228 => _228.eventListener, 'optionalAccess', _229 => _229.onNetworkStatistics, 'optionalCall', _230 => _230(Object.freeze({
           uplinkQuality: quality(stats.uplinkNetworkQuality),
           downlinkQuality: quality(stats.downlinkNetworkQuality),
           uplinkRttMs: rtt(stats.uplinkRTT),
@@ -2540,36 +2808,36 @@ var TrtcRtcManager = class {
       source.off(RTC_EVENT.networkQuality, onNetworkQuality);
     };
     source.on(RTC_EVENT.remoteVideoAvailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (_optionalChain([this, 'access', _231 => _231.lease, 'optionalAccess', _232 => _232.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
-      _optionalChain([this, 'access', _179 => _179.eventListener, 'optionalAccess', _180 => _180.onRemoteVideoPublished, 'call', _181 => _181(event.userId, true)]);
+      _optionalChain([this, 'access', _233 => _233.eventListener, 'optionalAccess', _234 => _234.onRemoteVideoPublished, 'call', _235 => _235(event.userId, true)]);
     });
     source.on(RTC_EVENT.remoteVideoUnavailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (_optionalChain([this, 'access', _236 => _236.lease, 'optionalAccess', _237 => _237.engine]) !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
-      _optionalChain([this, 'access', _182 => _182.eventListener, 'optionalAccess', _183 => _183.onRemoteVideoPublished, 'call', _184 => _184(event.userId, false)]);
+      _optionalChain([this, 'access', _238 => _238.eventListener, 'optionalAccess', _239 => _239.onRemoteVideoPublished, 'call', _240 => _240(event.userId, false)]);
     });
     source.on(RTC_EVENT.customMessage, (event) => {
-      if (event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
+      if (_optionalChain([this, 'access', _241 => _241.lease, 'optionalAccess', _242 => _242.engine]) !== engine || event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
         return;
       }
       let message;
       try {
         message = new TextDecoder().decode(event.data);
-      } catch (e13) {
+      } catch (e14) {
         XmaxLogger.rtc.warning(() => "\u81EA\u5B9A\u4E49\u6D88\u606F\u89E3\u7801\u5931\u8D25 (Failed to Decode Custom Message)");
         return;
       }
-      _optionalChain([this, 'access', _185 => _185.eventListener, 'optionalAccess', _186 => _186.onCustomMessageReceived, 'call', _187 => _187(event.userId, message)]);
+      _optionalChain([this, 'access', _243 => _243.eventListener, 'optionalAccess', _244 => _244.onCustomMessageReceived, 'call', _245 => _245(event.userId, message)]);
     });
   }
   /**
    * 返回当前引擎实例；未初始化时抛出错误。
    */
   requireEngine() {
-    const engine = _optionalChain([this, 'access', _188 => _188.lease, 'optionalAccess', _189 => _189.engine]);
+    const engine = _optionalChain([this, 'access', _246 => _246.lease, 'optionalAccess', _247 => _247.engine]);
     if (!engine) {
       throw new XmaxError(
         "RTC_ERROR" /* rtcError */,
@@ -2586,8 +2854,8 @@ var TrtcRtcManager = class {
       return error;
     }
     const rtcError = error;
-    const originName = _nullishCoalesce(_optionalChain([rtcError, 'optionalAccess', _190 => _190.originError, 'optionalAccess', _191 => _191.name]), () => ( ""));
-    const message = typeof _optionalChain([rtcError, 'optionalAccess', _192 => _192.message]) === "string" && rtcError.message.trim().length > 0 ? rtcError.message.trim() : String(error);
+    const originName = _nullishCoalesce(_optionalChain([rtcError, 'optionalAccess', _248 => _248.originError, 'optionalAccess', _249 => _249.name]), () => ( ""));
+    const message = typeof _optionalChain([rtcError, 'optionalAccess', _250 => _250.message]) === "string" && rtcError.message.trim().length > 0 ? rtcError.message.trim() : String(error);
     if (originName === "NotAllowedError" || originName === "SecurityError" || /NotAllowed/i.test(message)) {
       return new XmaxError("CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */, message);
     }
@@ -2645,6 +2913,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 +2973,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;
-    _optionalChain([engine, 'optionalAccess', _193 => _193.removeAllListeners, 'call', _194 => _194()]);
-    if (engine && sdk) sdk.default.destroyEngine(engine);
+    _optionalChain([engine, 'optionalAccess', _251 => _251.removeAllListeners, 'call', _252 => _252()]);
+    try {
+      if (engine && sdk) sdk.default.destroyEngine(engine);
+    } finally {
+      _optionalChain([this, 'access', _253 => _253.externalVideo, 'optionalAccess', _254 => _254.stop, 'call', _255 => _255()]);
+      _optionalChain([this, 'access', _256 => _256.externalAudio, 'optionalAccess', _257 => _257.stop, 'call', _258 => _258()]);
+      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 = _optionalChain([tracks, 'access', _259 => _259.audioTrack, 'optionalAccess', _260 => _260.clone, 'call', _261 => _261()]);
+      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();
+      _optionalChain([audio, 'optionalAccess', _262 => _262.stop, 'call', _263 => _263()]);
+      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 +3082,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",
@@ -2767,12 +3103,12 @@ var VeRtcManager = class {
     }));
   }
   async joinRoom(config) {
-    await _optionalChain([this, 'access', _195 => _195.joining, 'optionalAccess', _196 => _196.catch, 'call', _197 => _197(() => {
+    await _optionalChain([this, 'access', _264 => _264.joining, 'optionalAccess', _265 => _265.catch, 'call', _266 => _266(() => {
     })]);
-    await _optionalChain([this, 'access', _198 => _198.recovery, 'optionalAccess', _199 => _199.catch, 'call', _200 => _200(() => {
+    await _optionalChain([this, 'access', _267 => _267.recovery, 'optionalAccess', _268 => _268.catch, 'call', _269 => _269(() => {
     })]);
     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();
@@ -2818,8 +3154,8 @@ var VeRtcManager = class {
   async updateCredentials(config, signal) {
     const engine = this.requireEngine();
     const current = this.connection;
-    if (_optionalChain([signal, 'optionalAccess', _201 => _201.aborted])) throw this.cancelled();
-    if (!current || config.provider !== "vertc" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+    if (_optionalChain([signal, 'optionalAccess', _270 => _270.aborted])) throw this.cancelled();
+    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;
@@ -2846,7 +3182,7 @@ var VeRtcManager = class {
     const restore = this.tokenExpired || this.publishPrivilegeExpired || this.subscribePrivilegeExpired;
     if (restore) {
       this.joined = false;
-      _optionalChain([this, 'access', _202 => _202.listener, 'optionalAccess', _203 => _203.onRoomRejoining, 'optionalCall', _204 => _204()]);
+      _optionalChain([this, 'access', _271 => _271.listener, 'optionalAccess', _272 => _272.onRoomRejoining, 'optionalCall', _273 => _273()]);
       this.clearPlayers();
       this.clearStatistics();
       if (this.tokenExpired) {
@@ -2861,7 +3197,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 +3205,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 +3229,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 +3243,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 +3263,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() {
@@ -3014,13 +3353,13 @@ var VeRtcManager = class {
       if (!active()) return;
       if (video(mediaType)) {
         this.publishedVideo.add(userId);
-        if (mediaActive()) _optionalChain([this, 'access', _205 => _205.listener, 'optionalAccess', _206 => _206.onRemoteVideoPublished, 'call', _207 => _207(userId, true)]);
+        if (mediaActive()) _optionalChain([this, 'access', _274 => _274.listener, 'optionalAccess', _275 => _275.onRemoteVideoPublished, 'call', _276 => _276(userId, true)]);
       }
       if (audio(mediaType)) {
         this.publishedAudio.add(userId);
         if (mediaActive() && this.requestedAudio.has(userId)) {
           void this.subscribeRemoteAudio(userId, true).catch((error) => {
-            if (mediaActive()) _optionalChain([this, 'access', _208 => _208.listener, 'optionalAccess', _209 => _209.onError, 'optionalCall', _210 => _210(this.mapError(error))]);
+            if (mediaActive()) _optionalChain([this, 'access', _277 => _277.listener, 'optionalAccess', _278 => _278.onError, 'optionalCall', _279 => _279(this.mapError(error))]);
           });
         }
       }
@@ -3040,10 +3379,10 @@ var VeRtcManager = class {
       this.clearPlayer(userInfo.userId);
     });
     engine.on(events.onRoomMessageReceived, ({ userId, message }) => {
-      if (mediaActive() && typeof message === "string") _optionalChain([this, 'access', _211 => _211.listener, 'optionalAccess', _212 => _212.onCustomMessageReceived, 'call', _213 => _213(userId, message)]);
+      if (mediaActive() && typeof message === "string") _optionalChain([this, 'access', _280 => _280.listener, 'optionalAccess', _281 => _281.onCustomMessageReceived, 'call', _282 => _282(userId, message)]);
     });
     const willExpire = () => {
-      if (active()) _optionalChain([this, 'access', _214 => _214.listener, 'optionalAccess', _215 => _215.onTokenWillExpire, 'optionalCall', _216 => _216()]);
+      if (active()) _optionalChain([this, 'access', _283 => _283.listener, 'optionalAccess', _284 => _284.onTokenWillExpire, 'optionalCall', _285 => _285()]);
     };
     engine.on(events.onTokenWillExpire, willExpire);
     engine.on(events.onTokenPublishPrivilegeWillExpire, willExpire);
@@ -3051,13 +3390,13 @@ var VeRtcManager = class {
     engine.on(events.onTokenPublishPrivilegeDidExpired, () => {
       if (!active() || this.publishPrivilegeExpired) return;
       this.publishPrivilegeExpired = true;
-      _optionalChain([this, 'access', _217 => _217.listener, 'optionalAccess', _218 => _218.onTokenExpired, 'optionalCall', _219 => _219()]);
+      _optionalChain([this, 'access', _286 => _286.listener, 'optionalAccess', _287 => _287.onTokenExpired, 'optionalCall', _288 => _288()]);
     });
     engine.on(events.onTokenSubscribePrivilegeDidExpired, () => {
       if (!active() || this.subscribePrivilegeExpired) return;
       this.subscribePrivilegeExpired = true;
       this.clearPlayers();
-      _optionalChain([this, 'access', _220 => _220.listener, 'optionalAccess', _221 => _221.onTokenExpired, 'optionalCall', _222 => _222()]);
+      _optionalChain([this, 'access', _289 => _289.listener, 'optionalAccess', _290 => _290.onTokenExpired, 'optionalCall', _291 => _291()]);
     });
     engine.on(events.onError, ({ errorCode }) => {
       if (!active()) return;
@@ -3065,23 +3404,23 @@ var VeRtcManager = class {
         if (this.tokenExpired) return;
         this.tokenExpired = true;
         this.clearPlayers();
-        _optionalChain([this, 'access', _223 => _223.listener, 'optionalAccess', _224 => _224.onTokenExpired, 'optionalCall', _225 => _225()]);
-      } else _optionalChain([this, 'access', _226 => _226.listener, 'optionalAccess', _227 => _227.onError, 'optionalCall', _228 => _228(this.mapError({ code: errorCode }))]);
+        _optionalChain([this, 'access', _292 => _292.listener, 'optionalAccess', _293 => _293.onTokenExpired, 'optionalCall', _294 => _294()]);
+      } else _optionalChain([this, 'access', _295 => _295.listener, 'optionalAccess', _296 => _296.onError, 'optionalCall', _297 => _297(this.mapError({ code: errorCode }))]);
     });
     engine.on(events.onConnectionStateChanged, ({ state: state2 }) => {
       if (!mediaActive() || state2 !== this.sdk.ConnectionState.CONNECTION_STATE_RECONNECTED) return;
-      _optionalChain([this, 'access', _229 => _229.listener, 'optionalAccess', _230 => _230.onRoomRejoining, 'optionalCall', _231 => _231()]);
+      _optionalChain([this, 'access', _298 => _298.listener, 'optionalAccess', _299 => _299.onRoomRejoining, 'optionalCall', _300 => _300()]);
       this.clearPlayers();
       this.clearStatistics();
       this.replayVideo();
       for (const userID of this.requestedAudio) {
         void this.subscribeRemoteAudio(userID, true).catch((error) => {
-          if (mediaActive()) _optionalChain([this, 'access', _232 => _232.listener, 'optionalAccess', _233 => _233.onError, 'optionalCall', _234 => _234(this.mapError(error))]);
+          if (mediaActive()) _optionalChain([this, 'access', _301 => _301.listener, 'optionalAccess', _302 => _302.onError, 'optionalCall', _303 => _303(this.mapError(error))]);
         });
       }
     });
     engine.on(events.onNetworkQuality, (up, down) => {
-      if (mediaActive()) _optionalChain([this, 'access', _235 => _235.listener, 'optionalAccess', _236 => _236.onNetworkStatistics, 'optionalCall', _237 => _237(Object.freeze({
+      if (mediaActive()) _optionalChain([this, 'access', _304 => _304.listener, 'optionalAccess', _305 => _305.onNetworkStatistics, 'optionalCall', _306 => _306(Object.freeze({
         uplinkQuality: VeRtcStatistics.quality(up),
         downlinkQuality: VeRtcStatistics.quality(down)
       }))]);
@@ -3090,7 +3429,7 @@ var VeRtcManager = class {
       if (!mediaActive() || stats.isScreen || !this.videoRequested) return;
       const result = VeRtcStatistics.local(stats.videoStats);
       this.uplinkLossPercent = result.uplinkLossPercent;
-      _optionalChain([this, 'access', _238 => _238.listener, 'optionalAccess', _239 => _239.onLocalVideoStatistics, 'optionalCall', _240 => _240(result)]);
+      _optionalChain([this, 'access', _307 => _307.listener, 'optionalAccess', _308 => _308.onLocalVideoStatistics, 'optionalCall', _309 => _309(result)]);
       XmaxLogger.rtc.info(() => `VeRTC local video statistics: ${JSON.stringify(result)}`, 2 /* performance */);
     });
     engine.on(events.onRemoteStreamStats, (stats) => {
@@ -3100,21 +3439,21 @@ var VeRtcManager = class {
     });
   }
   replayVideo() {
-    for (const userID of this.publishedVideo) _optionalChain([this, 'access', _241 => _241.listener, 'optionalAccess', _242 => _242.onRemoteVideoPublished, 'call', _243 => _243(userID, true)]);
+    for (const userID of this.publishedVideo) _optionalChain([this, 'access', _310 => _310.listener, 'optionalAccess', _311 => _311.onRemoteVideoPublished, 'call', _312 => _312(userID, true)]);
   }
   removeVideo(userID) {
     this.publishedVideo.delete(userID);
     this.remoteStatistics.delete(userID);
     this.emitRemoteStatistics();
-    if (this.joined && !this.tokenExpired) _optionalChain([this, 'access', _244 => _244.listener, 'optionalAccess', _245 => _245.onRemoteVideoPublished, 'call', _246 => _246(userID, false)]);
+    if (this.joined && !this.tokenExpired) _optionalChain([this, 'access', _313 => _313.listener, 'optionalAccess', _314 => _314.onRemoteVideoPublished, 'call', _315 => _315(userID, false)]);
   }
   emitRemoteStatistics() {
-    _optionalChain([this, 'access', _247 => _247.listener, 'optionalAccess', _248 => _248.onRemoteVideoStatistics, 'optionalCall', _249 => _249(Object.freeze([...this.remoteStatistics.values()]))]);
+    _optionalChain([this, 'access', _316 => _316.listener, 'optionalAccess', _317 => _317.onRemoteVideoStatistics, 'optionalCall', _318 => _318(Object.freeze([...this.remoteStatistics.values()]))]);
   }
   clearStatistics() {
     this.remoteStatistics.clear();
     this.uplinkLossPercent = void 0;
-    _optionalChain([this, 'access', _250 => _250.listener, 'optionalAccess', _251 => _251.onLocalVideoStatistics, 'optionalCall', _252 => _252(void 0)]);
+    _optionalChain([this, 'access', _319 => _319.listener, 'optionalAccess', _320 => _320.onLocalVideoStatistics, 'optionalCall', _321 => _321(void 0)]);
     this.emitRemoteStatistics();
   }
   clearPlayer(userID) {
@@ -3160,15 +3499,15 @@ var VeRtcManager = class {
       const cleanup = () => {
         clearTimeout(timer);
         roomSignal.removeEventListener("abort", cancel);
-        _optionalChain([signal, 'optionalAccess', _253 => _253.removeEventListener, 'call', _254 => _254("abort", cancel)]);
+        _optionalChain([signal, 'optionalAccess', _322 => _322.removeEventListener, 'call', _323 => _323("abort", cancel)]);
       };
       const cancel = () => {
-        if (_optionalChain([signal, 'optionalAccess', _255 => _255.aborted]) && !roomSignal.aborted) this.roomVersion++;
+        if (_optionalChain([signal, 'optionalAccess', _324 => _324.aborted]) && !roomSignal.aborted) this.roomVersion++;
         cleanup();
         reject(this.cancelled());
       };
       roomSignal.addEventListener("abort", cancel, { once: true });
-      _optionalChain([signal, 'optionalAccess', _256 => _256.addEventListener, 'call', _257 => _257("abort", cancel, { once: true })]);
+      _optionalChain([signal, 'optionalAccess', _325 => _325.addEventListener, 'call', _326 => _326("abort", cancel, { once: true })]);
       task.then((value) => {
         cleanup();
         resolve(value);
@@ -3176,7 +3515,7 @@ var VeRtcManager = class {
         cleanup();
         reject(error);
       });
-      if (roomSignal.aborted || _optionalChain([signal, 'optionalAccess', _258 => _258.aborted])) cancel();
+      if (roomSignal.aborted || _optionalChain([signal, 'optionalAccess', _327 => _327.aborted])) cancel();
     });
   }
   isCurrent(engine, version) {
@@ -3189,6 +3528,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;
@@ -3203,8 +3551,8 @@ var VeRtcManager = class {
   mapError(error, permissionCode) {
     if (error instanceof XmaxError) return error;
     const value = error;
-    const code = typeof _optionalChain([value, 'optionalAccess', _259 => _259.code]) === "string" && /^[A-Z_0-9-]{1,64}$/.test(value.code) ? value.code : "UNKNOWN";
-    const denied = _optionalChain([value, 'optionalAccess', _260 => _260.name]) === "NotAllowedError" || code === "PERMISSION_DENIED" || code === "DEVICE_PERMISSION_DENIED";
+    const code = typeof _optionalChain([value, 'optionalAccess', _328 => _328.code]) === "string" && /^[A-Z_0-9-]{1,64}$/.test(value.code) ? value.code : "UNKNOWN";
+    const denied = _optionalChain([value, 'optionalAccess', _329 => _329.name]) === "NotAllowedError" || code === "PERMISSION_DENIED" || code === "DEVICE_PERMISSION_DENIED";
     return new XmaxError(permissionCode && denied ? permissionCode : "RTC_ERROR" /* rtcError */, `VeRTC operation failed (${code})`);
   }
   cancelled() {
@@ -3215,12 +3563,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");
   }
 }
 
@@ -3284,7 +3634,7 @@ var PermissionManager = class {
    * @param deniedCode 权限被拒绝时抛出的错误码。
    */
   async ensurePermission(name, deniedCode) {
-    if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _261 => _261.mediaDevices, 'optionalAccess', _262 => _262.getUserMedia])) {
+    if (typeof navigator === "undefined" || !_optionalChain([navigator, 'access', _330 => _330.mediaDevices, 'optionalAccess', _331 => _331.getUserMedia])) {
       throw new XmaxError(
         deniedCode,
         "This browser does not support media capture (getUserMedia)"
@@ -3292,7 +3642,7 @@ var PermissionManager = class {
     }
     try {
       const permissions = navigator.permissions;
-      if (!_optionalChain([permissions, 'optionalAccess', _263 => _263.query])) {
+      if (!_optionalChain([permissions, 'optionalAccess', _332 => _332.query])) {
         return;
       }
       const status = await permissions.query({
@@ -3472,10 +3822,10 @@ var _CameraController = class _CameraController {
      */
     __publicField(this, "storedUseMicrophone", false);
     __publicField(this, "storedFrameValidationEnabled", true);
-    this.permissionManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _264 => _264.permissionManager]), () => ( new PermissionManager()));
-    this.rtcManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _265 => _265.rtcManager]), () => ( new TrtcRtcManager()));
-    this.mediaService = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _266 => _266.mediaService]), () => ( new MediaService()));
-    this.errorListener = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _267 => _267.errorListener]), () => ( (() => {
+    this.permissionManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _333 => _333.permissionManager]), () => ( new PermissionManager()));
+    this.rtcManager = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _334 => _334.rtcManager]), () => ( new TrtcRtcManager()));
+    this.mediaService = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _335 => _335.mediaService]), () => ( new MediaService()));
+    this.errorListener = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _336 => _336.errorListener]), () => ( (() => {
     })));
   }
   /**
@@ -3501,7 +3851,7 @@ var _CameraController = class _CameraController {
    */
   async waitForValidCameraFrame(signal) {
     const track = this.activeTrack;
-    const mediaTrack = _optionalChain([track, 'optionalAccess', _268 => _268.mediaStreamTrack]);
+    const mediaTrack = _optionalChain([track, 'optionalAccess', _337 => _337.mediaStreamTrack]);
     if (!mediaTrack) throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera capture is not running");
     if (signal.aborted) throw new XmaxError("CANCELLED" /* cancelled */, "Camera frame validation cancelled");
     if (!this.isFrameValidationEnabled) return;
@@ -3601,7 +3951,7 @@ var _CameraController = class _CameraController {
    */
   async switchCamera() {
     const track = this.activeTrack;
-    const position = _optionalChain([track, 'optionalAccess', _269 => _269.position]);
+    const position = _optionalChain([track, 'optionalAccess', _338 => _338.position]);
     if (!track || !position) {
       throw new XmaxError(
         "RTC_ERROR" /* rtcError */,
@@ -3619,7 +3969,7 @@ var _CameraController = class _CameraController {
       }
       this.previewStream.addTrack(mediaTrack);
     }
-    _optionalChain([this, 'access', _270 => _270.previewMirrorApplier, 'optionalCall', _271 => _271(nextPosition === "front" /* front */)]);
+    _optionalChain([this, 'access', _339 => _339.previewMirrorApplier, 'optionalCall', _340 => _340(nextPosition === "front" /* front */)]);
     this.observeMediaTrack(track, mediaTrack);
     return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
   }
@@ -3715,6 +4065,463 @@ var _CameraController = class _CameraController {
 __publicField(_CameraController, "localVideoTrackID", "video0");
 var CameraController = _CameraController;
 
+// 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() {
+    /**
+     * 当前视频源与完成通知
+     */
+    __publicField(this, "currentTrack");
+    __publicField(this, "reference");
+    __publicField(this, "onFinish");
+    /**
+     * 预览进度与视图资源
+     */
+    __publicField(this, "position", 0);
+    __publicField(this, "ended", false);
+    __publicField(this, "bindings", /* @__PURE__ */ new Map());
+  }
+  /**
+   * 创建网络视频源，校验地址、采样方式和模型支持的尺寸；不请求视频下载。
+   */
+  create(options, mediaService) {
+    let url;
+    try {
+      url = new URL(options.url);
+    } catch (e15) {
+      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 = _nullishCoalesce(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);
+      _optionalChain([view, 'access', _341 => _341.setVideoURL, 'optionalCall', _342 => _342(null)]);
+    });
+    view.isMirrored = false;
+    view.setVideoURL(this.reference.path);
+  }
+  /**
+   * 保存预览进度并释放该视图的地址和事件监听。
+   */
+  detach(view) {
+    _optionalChain([this, 'access', _343 => _343.bindings, 'access', _344 => _344.get, 'call', _345 => _345(view), 'optionalCall', _346 => _346()]);
+    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 _optionalChain([this, 'access', _347 => _347.source, 'optionalAccess', _348 => _348.track]);
+  }
+  /**
+   * 文件音频输出；禁用音频时为空，无音轨文件的 Web Audio 输出为静音。
+   */
+  get audioTrack() {
+    return _optionalChain([this, 'access', _349 => _349.source, 'optionalAccess', _350 => _350.audioDestination, 'optionalAccess', _351 => _351.stream, 'access', _352 => _352.getAudioTracks, 'call', _353 => _353(), 'access', _354 => _354[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 = _nullishCoalesce(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 = _optionalChain([source, 'access', _355 => _355.audioContext, 'optionalAccess', _356 => _356.resume, 'call', _357 => _357()]);
+      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 (e16) {
+          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 (!_optionalChain([source, 'optionalAccess', _358 => _358.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([_optionalChain([source, 'access', _359 => _359.audioContext, 'optionalAccess', _360 => _360.resume, 'call', _361 => _361()]), this.play(source, signal)]), signal);
+    } catch (error) {
+      source.video.pause();
+      throw error;
+    }
+  }
+  /**
+   * 暂停文件音视频，保留当前预览；重新开始生成时回到文件开头。
+   */
+  pause() {
+    _optionalChain([this, 'access', _362 => _362.source, 'optionalAccess', _363 => _363.video, 'access', _364 => _364.pause, 'call', _365 => _365()]);
+  }
+  /**
+   * 释放播放器、预览、定时器、轨道、音频上下文和对象 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 (e17) {
+      }
+    }
+    source.targets.clear();
+    source.video.pause();
+    source.video.removeAttribute("src");
+    source.video.load();
+    _optionalChain([source, 'access', _366 => _366.stream, 'optionalAccess', _367 => _367.getTracks, 'call', _368 => _368(), 'access', _369 => _369.forEach, 'call', _370 => _370((track) => track.stop())]);
+    _optionalChain([source, 'access', _371 => _371.audioDestination, 'optionalAccess', _372 => _372.stream, 'access', _373 => _373.getTracks, 'call', _374 => _374(), 'access', _375 => _375.forEach, 'call', _376 => _376((track) => track.stop())]);
+    _optionalChain([source, 'access', _377 => _377.audioSource, 'optionalAccess', _378 => _378.disconnect, 'call', _379 => _379()]);
+    _optionalChain([source, 'access', _380 => _380.audioDestination, 'optionalAccess', _381 => _381.disconnect, 'call', _382 => _382()]);
+    URL.revokeObjectURL(source.url);
+    await _optionalChain([source, 'access', _383 => _383.audioContext, 'optionalAccess', _384 => _384.close, 'call', _385 => _385(), 'access', _386 => _386.catch, 'call', _387 => _387(() => {
+    })]);
+  }
+  /**
+   * 播放被浏览器拒绝时给出可操作错误；关闭后的迟到播放立即暂停。
+   */
+  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(_nullishCoalesce(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 = _optionalChain([init, 'access', _388 => _388.referencePath, 'optionalAccess', _389 => _389.trim, 'call', _390 => _390()]);
+    this.referencePath = normalizedReferencePath || void 0;
+  }
+};
+
 // src/Service/Realtime/RealtimeSession.ts
 var RealtimeSession = class {
   /**
@@ -3779,7 +4586,7 @@ var RoomJoinConfiguration = class {
     /**
      * RTC 提供方。
      */
-    __publicField(this, "provider", "trtc");
+    __publicField(this, "provider", "trtc" /* trtc */);
     /**
      * 进房参数
      */
@@ -3872,10 +4679,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
@@ -3978,7 +4785,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
           return;
         }
         _RealtimeSessionService.ensureSessionActive(session);
-        await _optionalChain([handlers, 'access', _272 => _272.onRefresh, 'optionalCall', _273 => _273(session)]);
+        await _optionalChain([handlers, 'access', _391 => _391.onRefresh, 'optionalCall', _392 => _392(session)]);
       } catch (error) {
         if (this.heartbeatVersion !== version) {
           return;
@@ -4090,7 +4897,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
       return void 0;
     }
     return new RealtimeSessionConnection({
-      provider: "trtc",
+      provider: "trtc" /* trtc */,
       roomID,
       sdkAppID,
       userID,
@@ -4106,7 +4913,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
     if (typeof modelExtra === "string") {
       try {
         return _RealtimeSessionService.decodeConnectionPayload(JSON.parse(modelExtra));
-      } catch (e14) {
+      } catch (e18) {
         return void 0;
       }
     }
@@ -4191,7 +4998,7 @@ var RealtimeState = class {
    * @param other 待比较的状态。
    */
   equals(other) {
-    return this.connectionState === other.connectionState && this.sessionID === other.sessionID && this.taskID === other.taskID && _optionalChain([this, 'access', _274 => _274.reason, 'optionalAccess', _275 => _275.kind]) === _optionalChain([other, 'access', _276 => _276.reason, 'optionalAccess', _277 => _277.kind]);
+    return this.connectionState === other.connectionState && this.sessionID === other.sessionID && this.taskID === other.taskID && _optionalChain([this, 'access', _393 => _393.reason, 'optionalAccess', _394 => _394.kind]) === _optionalChain([other, 'access', _395 => _395.reason, 'optionalAccess', _396 => _396.kind]);
   }
 };
 
@@ -4234,9 +5041,20 @@ var RoomEvent = class _RoomEvent {
   static start(options) {
     return _RoomEvent.encode({
       event: "start",
-      params: _RoomEvent.generationParameters(options),
+      params: {
+        ..._RoomEvent.generationParameters(options),
+        ...options.context.referenceVideo && {
+          ref_video_path: options.context.referenceVideo.path,
+          sample_method: options.context.referenceVideo.sampleMethod,
+          target_size: [
+            _nullishCoalesce(_optionalChain([options, 'access', _397 => _397.targetSize, 'optionalAccess', _398 => _398.width]), () => ( options.videoFormat.width)),
+            _nullishCoalesce(_optionalChain([options, 'access', _399 => _399.targetSize, 'optionalAccess', _400 => _400.height]), () => ( options.videoFormat.height))
+          ]
+        }
+      },
       user_id: options.userID,
-      uid: options.taskID
+      uid: options.taskID,
+      ...options.context.referenceVideo && { session_uid: options.taskID }
     });
   }
   /**
@@ -4317,7 +5135,7 @@ var RoomEvent = class _RoomEvent {
   static encode(payload) {
     try {
       return JSON.stringify({ ...payload, runtime: RuntimeInfo.toJSON() });
-    } catch (e15) {
+    } catch (e19) {
       throw new XmaxError(
         "INTERNAL_ERROR" /* internalError */,
         "Failed to encode RTC room event"
@@ -4443,7 +5261,7 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     let parsed;
     try {
       parsed = JSON.parse(message);
-    } catch (e16) {
+    } catch (e20) {
       XmaxLogger.room.warning(() => "\u623F\u95F4\u6D88\u606F\u4E0D\u662F\u5408\u6CD5 JSON (Room Message Is Not Valid JSON)");
       return void 0;
     }
@@ -4452,20 +5270,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;
       }
@@ -4474,7 +5292,7 @@ var _RoomMessageCodec = class _RoomMessageCodec {
     const joined = parts.join("");
     try {
       return JSON.parse(joined);
-    } catch (e17) {
+    } catch (e21) {
       XmaxLogger.room.warning(
         () => `\u623F\u95F4\u6D88\u606F\u7EC4\u5305\u540E\u4E0D\u662F\u5408\u6CD5 JSON (Reassembled Message Is Not Valid JSON)
 \u2514\u2500 eventId: ${chunk.eventId}`
@@ -4495,16 +5313,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 +5434,9 @@ var RoomController = class {
    *
    * @throws 已有房间未离开、操作失效或进房失败时抛出错误。
    */
-  async join(connection, ensureActive) {
+  async join(connection, ensureActive2) {
     try {
-      ensureActive();
+      ensureActive2();
     } catch (error) {
       throw XmaxError.from(error);
     }
@@ -4633,10 +5451,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");
       }
@@ -4774,7 +5592,7 @@ var RoomController = class {
     if (targetUserID && ownUserID && targetUserID !== ownUserID) {
       return;
     }
-    _optionalChain([this, 'access', _278 => _278.listener, 'optionalAccess', _279 => _279.onRoomMessage, 'call', _280 => _280(senderUserID, message)]);
+    _optionalChain([this, 'access', _401 => _401.listener, 'optionalAccess', _402 => _402.onRoomMessage, 'call', _403 => _403(senderUserID, message)]);
   }
   /**
    * 发送房间信令并输出日志。
@@ -5019,6 +5837,7 @@ var StreamController = class {
      * 运行状态
      */
     __publicField(this, "state", makeInitialState());
+    __publicField(this, "roomListener");
     this.rtcManager = options.rtcManager;
     this.roomController = _nullishCoalesce(options.roomController, () => ( new RoomController({ rtcManager: options.rtcManager })));
     this.encodingController = _nullishCoalesce(options.encodingController, () => ( new EncodingController({ rtcManager: options.rtcManager })));
@@ -5027,25 +5846,31 @@ var StreamController = class {
     this.remoteStreamListener = _nullishCoalesce(options.remoteStreamListener, () => ( (() => {
     })));
     this.generationTimeoutMs = _nullishCoalesce(options.generationTimeoutMs, () => ( 3e4));
+    this.roomController.setListener({
+      onRoomMessage: (sender, message) => {
+        this.handleNetworkVideoCompletion(sender, message);
+        _optionalChain([this, 'access', _404 => _404.roomListener, 'optionalAccess', _405 => _405.onRoomMessage, 'call', _406 => _406(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) {
-          _optionalChain([this, 'access', _281 => _281.networkStatisticsListener, 'optionalCall', _282 => _282(statistics)]);
+        if (this.state.roomID) {
+          _optionalChain([this, 'access', _407 => _407.networkStatisticsListener, 'optionalCall', _408 => _408(statistics)]);
         }
       },
       onRemoteVideoStatistics: (statistics) => {
-        const userID = _optionalChain([this, 'access', _283 => _283.state, 'access', _284 => _284.activeRemoteStream, 'optionalAccess', _285 => _285.userID]);
-        _optionalChain([this, 'access', _286 => _286.remoteVideoStatisticsListener, 'optionalCall', _287 => _287(
+        const userID = _optionalChain([this, 'access', _409 => _409.state, 'access', _410 => _410.activeRemoteStream, 'optionalAccess', _411 => _411.userID]);
+        _optionalChain([this, 'access', _412 => _412.remoteVideoStatisticsListener, 'optionalCall', _413 => _413(
           userID ? statistics.find((item) => item.userID === userID) : void 0
         )]);
       },
       onLocalVideoStatistics: (statistics) => {
         if (this.state.localVideoPublished) {
-          _optionalChain([this, 'access', _288 => _288.localVideoStatisticsListener, 'optionalCall', _289 => _289(statistics)]);
+          _optionalChain([this, 'access', _414 => _414.localVideoStatisticsListener, 'optionalCall', _415 => _415(statistics)]);
         }
       },
       onCustomMessageReceived: (senderUserID, message) => {
@@ -5109,17 +5934,19 @@ var StreamController = class {
    *
    * @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: ${_nullishCoalesce(connection.botID, () => ( "(\u672A\u8BBE\u7F6E)"))}`
     );
-    await _optionalChain([beforePublish, 'optionalCall', _290 => _290()]);
-    ensureActive();
-    await this.publishLocalStream(includeLocalAudio);
+    if (publishLocalMedia) {
+      await _optionalChain([beforePublish, 'optionalCall', _416 => _416()]);
+      ensureActive2();
+      await this.publishLocalStream(includeLocalAudio);
+    }
   }
   /**
    * 清理生成状态、本地发布和远端订阅，并离开当前 RTC 房间。
@@ -5180,6 +6007,7 @@ 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(() => {
     });
@@ -5191,7 +6019,9 @@ var StreamController = class {
         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 _optionalChain([options, 'access', _417 => _417.onStartSent, 'optionalCall', _418 => _418()]);
         if (this.state !== state2 || state2.generationTaskID !== taskID) return;
         for (const userID of state2.publishedRemoteUserIDs) {
           void this.handleRemoteVideoPublished(userID, true);
@@ -5215,7 +6045,7 @@ var StreamController = class {
       try {
         void this.roomController.stopGeneration(taskID).catch(() => {
         });
-      } catch (e18) {
+      } catch (e22) {
       }
       throw mapped;
     }
@@ -5257,9 +6087,9 @@ var StreamController = class {
    *
    * @throws 操作已取消、房间未就绪或信令发送失败时抛出错误。
    */
-  async changeTargetSize(taskID, targetSize, ensureActive) {
+  async changeTargetSize(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,14 +6126,57 @@ 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 (!_optionalChain([completion, 'optionalAccess', _419 => _419.finished]) || !completion.onFinish || completion.scheduled) {
+      return;
+    }
+    completion.scheduled = true;
+    queueMicrotask(() => {
+      if (this.state !== state2 || state2.generationTaskID !== completion.taskID) {
+        return;
+      }
+      try {
+        void Promise.resolve(_optionalChain([completion, 'access', _420 => _420.onFinish, 'optionalCall', _421 => _421()])).catch(() => {
+        });
+      } catch (e23) {
+      }
+    });
   }
   /**
    * 配置当前房间；已有发布、订阅或生成任务时拒绝重新配置。
    */
   configureRoom(options) {
     const roomID = options.roomID.trim();
-    const botID = _nullishCoalesce(_optionalChain([options, 'access', _291 => _291.botID, 'optionalAccess', _292 => _292.trim, 'call', _293 => _293()]), () => ( ""));
+    const botID = _nullishCoalesce(_optionalChain([options, 'access', _422 => _422.botID, 'optionalAccess', _423 => _423.trim, 'call', _424 => _424()]), () => ( ""));
     if (!roomID) {
       throw new XmaxError(
         "INVALID_CONFIGURATION" /* invalidConfiguration */,
@@ -5386,7 +6259,7 @@ var StreamController = class {
       return;
     }
     this.state.subscribedRemoteUserIDs.delete(trimmedUserID);
-    if (_optionalChain([this, 'access', _294 => _294.state, 'access', _295 => _295.activeRemoteStream, 'optionalAccess', _296 => _296.userID]) === trimmedUserID) {
+    if (_optionalChain([this, 'access', _425 => _425.state, 'access', _426 => _426.activeRemoteStream, 'optionalAccess', _427 => _427.userID]) === trimmedUserID) {
       await this.unsubscribeRemoteAudio(trimmedUserID);
       this.state.activeRemoteStream = void 0;
       this.clearRemoteStream();
@@ -5527,6 +6400,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) {
@@ -5575,7 +6449,7 @@ var StreamController = class {
    */
   resolveGenerationStart(taskID) {
     const waiter = this.state.generationWaiter;
-    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _297 => _297.taskID]) !== taskID) {
+    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _428 => _428.taskID]) !== taskID) {
       return;
     }
     this.state.generationWaiter = void 0;
@@ -5587,7 +6461,7 @@ var StreamController = class {
    */
   rejectGenerationStart(taskID, error) {
     const waiter = this.state.generationWaiter;
-    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _298 => _298.taskID]) !== taskID) {
+    if (this.state.generationTaskID !== taskID || _optionalChain([waiter, 'optionalAccess', _429 => _429.taskID]) !== taskID) {
       return;
     }
     this.state.generationWaiter = void 0;
@@ -5598,7 +6472,7 @@ var StreamController = class {
    * 通知渲染层清理远端生成流；失败仅记录日志。
    */
   clearRemoteStream() {
-    _optionalChain([this, 'access', _299 => _299.remoteVideoStatisticsListener, 'optionalCall', _300 => _300(void 0)]);
+    _optionalChain([this, 'access', _430 => _430.remoteVideoStatisticsListener, 'optionalCall', _431 => _431(void 0)]);
     try {
       this.remoteStreamListener(null);
     } catch (error) {
@@ -5869,7 +6743,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
         }
         throw _RealtimeCoordinator.cancelledError();
       }
-      const terminationTask = await _asyncNullishCoalesce(await _asyncNullishCoalesce(operation.terminationTask, async () => ( _optionalChain([this, 'access', _301 => _301.termination, 'optionalAccess', _302 => _302.task]))), async () => ( await this.requestTermination(
+      const terminationTask = await _asyncNullishCoalesce(await _asyncNullishCoalesce(operation.terminationTask, async () => ( _optionalChain([this, 'access', _432 => _432.termination, 'optionalAccess', _433 => _433.task]))), async () => ( await this.requestTermination(
         _nullishCoalesce(operation.lease.failureScope, () => ( 0)) /* connection */,
         void 0,
         RealtimeReason.normal,
@@ -5998,7 +6872,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
    * 结束指定操作，释放操作准入场。
    */
   finish(operation) {
-    if (_optionalChain([this, 'access', _303 => _303.activeOperation, 'optionalAccess', _304 => _304.id]) === operation.id) {
+    if (_optionalChain([this, 'access', _434 => _434.activeOperation, 'optionalAccess', _435 => _435.id]) === operation.id) {
       this.activeOperation = void 0;
     }
   }
@@ -6010,7 +6884,7 @@ var RealtimeCoordinator = class _RealtimeCoordinator {
       return;
     }
     this.state = nextState;
-    _optionalChain([this, 'access', _305 => _305.stateListener, 'optionalCall', _306 => _306(nextState)]);
+    _optionalChain([this, 'access', _436 => _436.stateListener, 'optionalCall', _437 => _437(nextState)]);
   }
   /**
    * 构造统一的操作取消错误。
@@ -6078,13 +6952,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;
   }
   /**
    * 开始等待用户授权系统媒体权限，返回授权决定时调用的记录函数。
@@ -6142,9 +7021,9 @@ var RealtimeLaunchTimer = class {
    */
   notify() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _307 => _307.listener, 'optionalCall', _308 => _308(this.snapshot)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _438 => _438.listener, 'optionalCall', _439 => _439(this.snapshot)])).catch(() => {
       });
-    } catch (e19) {
+    } catch (e24) {
     }
   }
 };
@@ -6174,7 +7053,7 @@ var XmaxRealtimeConnectionManager = class {
    * 当前活动会话标识；尚未连接或清理完成后为空。
    */
   get currentSessionID() {
-    return _optionalChain([this, 'access', _309 => _309.activeSession, 'optionalAccess', _310 => _310.id]);
+    return _optionalChain([this, 'access', _440 => _440.activeSession, 'optionalAccess', _441 => _441.id]);
   }
   /**
    * 未配置 API 服务时在连接操作开始前报错，不影响本地预览。
@@ -6215,19 +7094,23 @@ var XmaxRealtimeConnectionManager = class {
         "Local video stream has no video format"
       );
     }
-    await streamController.setVideoEncoderConfig(videoFormat);
+    const publishLocalMedia = _nullishCoalesce(options.publishLocalMedia, () => ( true));
+    if (publishLocalMedia) {
+      await streamController.setVideoEncoderConfig(videoFormat);
+    }
     options.ensureCurrent();
     let completePublish;
     await streamController.connect(connection, options.includeLocalAudio, () => {
       options.ensureCurrent();
     }, async () => {
       options.ensureCurrent();
-      await _optionalChain([options, 'access', _311 => _311.beforePublish, 'optionalCall', _312 => _312()]);
+      await _optionalChain([options, 'access', _442 => _442.beforePublish, 'optionalCall', _443 => _443()]);
       completeConnection();
       completePublish = this.dependencies.timing.startPublish();
-    });
+    }, publishLocalMedia);
     options.ensureCurrent();
-    _optionalChain([completePublish, 'optionalCall', _313 => _313()]);
+    completeConnection();
+    _optionalChain([completePublish, 'optionalCall', _444 => _444()]);
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
       onFailure: (sessionID, error) => {
@@ -6250,24 +7133,24 @@ var XmaxRealtimeConnectionManager = class {
    * 更新已绑定远端视图的插帧配置；传 undefined 停用插帧。
    */
   setFrameInterpolation(options) {
-    _optionalChain([this, 'access', _314 => _314.remoteTarget, 'optionalAccess', _315 => _315.setFrameInterpolation, 'optionalCall', _316 => _316(options)]);
+    _optionalChain([this, 'access', _445 => _445.remoteTarget, 'optionalAccess', _446 => _446.setFrameInterpolation, 'optionalCall', _447 => _447(options)]);
   }
   /**
    * 清空远端视图的媒体流，保留轨道与视图绑定以供统一清理。
    */
   clearRemoteMedia() {
-    _optionalChain([this, 'access', _317 => _317.remoteTarget, 'optionalAccess', _318 => _318.setMediaStream, 'call', _319 => _319(null)]);
+    _optionalChain([this, 'access', _448 => _448.remoteTarget, 'optionalAccess', _449 => _449.setMediaStream, 'call', _450 => _450(null)]);
   }
   /**
    * 停止会话心跳；未配置会话服务时不执行操作。
    */
   stopHeartbeat() {
     this.refreshVersion++;
-    _optionalChain([this, 'access', _320 => _320.credentialController, 'optionalAccess', _321 => _321.abort, 'call', _322 => _322()]);
+    _optionalChain([this, 'access', _451 => _451.credentialController, 'optionalAccess', _452 => _452.abort, 'call', _453 => _453()]);
     this.credentialController = void 0;
     this.credentialRefresh = void 0;
     this.credentialApplication = Promise.resolve();
-    _optionalChain([this, 'access', _323 => _323.dependencies, 'access', _324 => _324.sessionService, 'optionalAccess', _325 => _325.stopHeartbeat, 'call', _326 => _326()]);
+    _optionalChain([this, 'access', _454 => _454.dependencies, 'access', _455 => _455.sessionService, 'optionalAccess', _456 => _456.stopHeartbeat, 'call', _457 => _457()]);
   }
   /**
    * RTC Token 过期时复用会话心跳获取新凭据，并合并同一实例的并发请求。
@@ -6275,14 +7158,14 @@ var XmaxRealtimeConnectionManager = class {
   async refreshCredentials() {
     if (this.credentialRefresh) return this.credentialRefresh;
     const current = this.activeSession;
-    if (!_optionalChain([current, 'optionalAccess', _327 => _327.connection]) || current.connection.provider === "trtc") return;
+    if (!_optionalChain([current, 'optionalAccess', _458 => _458.connection]) || current.connection.provider === "trtc" /* trtc */) return;
     const version = this.refreshVersion;
     const operation = (async () => {
       try {
         const session = await this.requireSessionService().heartbeatSession(current.id);
         await this.handleSessionRefresh(session, version, true);
       } catch (error) {
-        if (version === this.refreshVersion && _optionalChain([this, 'access', _328 => _328.activeSession, 'optionalAccess', _329 => _329.id]) === current.id) {
+        if (version === this.refreshVersion && _optionalChain([this, 'access', _459 => _459.activeSession, 'optionalAccess', _460 => _460.id]) === current.id) {
           this.dependencies.onHeartbeatFailure(current.id, XmaxError.from(error));
         }
       }
@@ -6299,7 +7182,7 @@ var XmaxRealtimeConnectionManager = class {
    */
   async waitUntilRemoteTrackReady(timeoutMs, signal) {
     if (signal.aborted) throw RealtimeCoordinator.cancelledError();
-    const mediaTrack = _optionalChain([this, 'access', _330 => _330.activeRemoteTrack, 'optionalAccess', _331 => _331.mediaStreamTrack]);
+    const mediaTrack = _optionalChain([this, 'access', _461 => _461.activeRemoteTrack, 'optionalAccess', _462 => _462.mediaStreamTrack]);
     if (!mediaTrack || !mediaTrack.muted) return;
     await new Promise((resolve, reject) => {
       const cleanup = () => {
@@ -6336,7 +7219,7 @@ var XmaxRealtimeConnectionManager = class {
       if (track) {
         track.mediaStreamTrack = void 0;
       }
-      _optionalChain([this, 'access', _332 => _332.remoteTarget, 'optionalAccess', _333 => _333.setMediaStream, 'call', _334 => _334(null)]);
+      _optionalChain([this, 'access', _463 => _463.remoteTarget, 'optionalAccess', _464 => _464.setMediaStream, 'call', _465 => _465(null)]);
       return;
     }
     if (!track) {
@@ -6346,7 +7229,7 @@ var XmaxRealtimeConnectionManager = class {
       );
     }
     track.mediaStreamTrack = binding.videoTrack;
-    _optionalChain([this, 'access', _335 => _335.remoteTarget, 'optionalAccess', _336 => _336.setMediaStream, 'call', _337 => _337(new MediaStream([binding.videoTrack]))]);
+    _optionalChain([this, 'access', _466 => _466.remoteTarget, 'optionalAccess', _467 => _467.setMediaStream, 'call', _468 => _468(new MediaStream([binding.videoTrack]))]);
   }
   /**
    * 为远端轨道注册渲染绑定：attach 时挂流占位，媒体轨到达后送入画面。
@@ -6359,7 +7242,7 @@ var XmaxRealtimeConnectionManager = class {
         }
       },
       attachHandler: (view) => {
-        _optionalChain([this, 'access', _338 => _338.remoteTarget, 'optionalAccess', _339 => _339.setFrameInterpolation, 'optionalCall', _340 => _340(void 0)]);
+        _optionalChain([this, 'access', _469 => _469.remoteTarget, 'optionalAccess', _470 => _470.setFrameInterpolation, 'optionalCall', _471 => _471(void 0)]);
         view.isMirrored = this.dependencies.isMirrored();
         this.remoteTarget = view;
         this.dependencies.onRenderAttached();
@@ -6371,7 +7254,7 @@ var XmaxRealtimeConnectionManager = class {
           this.dependencies.onRenderDetached();
           this.remoteTarget = void 0;
         }
-        _optionalChain([view, 'access', _341 => _341.setFrameInterpolation, 'optionalCall', _342 => _342(void 0)]);
+        _optionalChain([view, 'access', _472 => _472.setFrameInterpolation, 'optionalCall', _473 => _473(void 0)]);
         view.setMediaStream(null);
       }
     });
@@ -6428,8 +7311,8 @@ var XmaxRealtimeConnectionManager = class {
       );
       return;
     }
-    if (next.provider !== "trtc" && (force || !previous || previous.provider === "trtc" || next.roomToken !== previous.roomToken)) {
-      await this.dependencies.streamController.updateCredentials(next, _optionalChain([this, 'access', _343 => _343.credentialController, 'optionalAccess', _344 => _344.signal]));
+    if (next.provider !== "trtc" /* trtc */ && (force || !previous || previous.provider === "trtc" /* trtc */ || next.roomToken !== previous.roomToken)) {
+      await this.dependencies.streamController.updateCredentials(next, _optionalChain([this, 'access', _474 => _474.credentialController, 'optionalAccess', _475 => _475.signal]));
       if (version !== this.refreshVersion || this.activeSession !== current) return;
     }
     this.activeSession = new RealtimeSession({
@@ -6444,7 +7327,7 @@ var XmaxRealtimeConnectionManager = class {
    * 尽力清理全部连接资源，即使退房失败也关闭服务端会话。
    */
   async disconnect() {
-    const sessionID = _optionalChain([this, 'access', _345 => _345.activeSession, 'optionalAccess', _346 => _346.id]);
+    const sessionID = _optionalChain([this, 'access', _476 => _476.activeSession, 'optionalAccess', _477 => _477.id]);
     this.stopHeartbeat();
     this.clearRemoteMedia();
     try {
@@ -6526,7 +7409,8 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       const confirmation = this.streamController.beginGeneration({
         taskID,
         videoFormat: options.videoFormat,
-        context
+        context,
+        ...options.onStartSent && { onStartSent: options.onStartSent }
       });
       await this.awaitConfirmation(confirmation, options.signal);
       options.ensureCurrent();
@@ -6578,7 +7462,7 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
     try {
       await completion;
     } finally {
-      if (_optionalChain([this, 'access', _347 => _347.pendingStop, 'optionalAccess', _348 => _348.completion]) === completion) this.pendingStop = void 0;
+      if (_optionalChain([this, 'access', _478 => _478.pendingStop, 'optionalAccess', _479 => _479.completion]) === completion) this.pendingStop = void 0;
     }
   }
   /**
@@ -6659,6 +7543,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");
     /**
      * 启动计时与首帧通知
      */
@@ -6692,18 +7581,19 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.options = options;
     this.mediaService = new MediaService(options.model);
     this.interpolationRequested = options.isFrameInterpolationEnabled;
-    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _349 => _349.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
+    this.supportsInterpolation = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _480 => _480.supportsFrameInterpolation]), () => ( (async (size) => await frameInterpolationAdapter(size) !== null)));
     this.errorHandler = new RealtimeErrorHandler();
-    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _350 => _350.rtcManager]), () => ( createRtcManager(options.provider, _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _351 => _351.environment]), () => ( "china")) /* china */)));
-    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _352 => _352.cameraController]), () => ( new CameraController({
+    const rtcManager = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _481 => _481.rtcManager]), () => ( createRtcManager(options.provider, _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _482 => _482.environment]), () => ( "china")) /* china */)));
+    this.rtcManager = rtcManager;
+    this.cameraController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _483 => _483.cameraController]), () => ( new CameraController({
       rtcManager,
       mediaService: this.mediaService,
       errorListener: (error) => {
         void this.errorHandler.report(error);
       }
     })));
-    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _353 => _353.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _354 => _354.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0)));
-    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _355 => _355.streamController]), () => ( new StreamController({
+    const sessionService = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _484 => _484.sessionService]), () => ( (_optionalChain([dependencies, 'optionalAccess', _485 => _485.apiService]) ? new RealtimeSessionService({ apiService: dependencies.apiService, provider: options.provider }) : void 0)));
+    this.streamController = _nullishCoalesce(_optionalChain([dependencies, 'optionalAccess', _486 => _486.streamController]), () => ( new StreamController({
       rtcManager,
       onCredentialsRequired: () => {
         void this.connectionManager.refreshCredentials();
@@ -6721,12 +7611,12 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       sessionService,
       streamController: this.streamController,
       timing: this.launchTimer,
-      isMirrored: () => _optionalChain([this, 'access', _356 => _356.cameraController, 'access', _357 => _357.currentTrack, 'optionalAccess', _358 => _358.position]) === "front" /* front */,
+      isMirrored: () => _optionalChain([this, 'access', _487 => _487.cameraController, 'access', _488 => _488.currentTrack, 'optionalAccess', _489 => _489.position]) === "front" /* front */,
       remoteAudioVolume: () => this.storedRemoteAudioVolume,
       onHeartbeatFailure: (sessionID, error) => {
         void this.handleHeartbeatFailure(sessionID, error);
       },
-      onFrameDisplayed: () => _optionalChain([this, 'access', _359 => _359.remoteFrameDisplayHandler, 'optionalCall', _360 => _360()]),
+      onFrameDisplayed: () => _optionalChain([this, 'access', _490 => _490.remoteFrameDisplayHandler, 'optionalCall', _491 => _491()]),
       onRenderAttached: () => this.applyRemoteInterpolation(),
       onRenderDetached: () => {
         this.interpolationRevision++;
@@ -6773,7 +7663,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = _nullishCoalesce(this.generationVideoFormat, () => ( _optionalChain([this, 'access', _361 => _361.cameraController, 'access', _362 => _362.currentTrack, 'optionalAccess', _363 => _363.videoFormat])));
+      const format = _nullishCoalesce(this.generationVideoFormat, () => ( _optionalChain([this, 'access', _492 => _492.currentLocalTrack, 'optionalAccess', _493 => _493.videoFormat])));
       const size = format && enabled ? this.mediaService.resolveFrameInterpolationSize(format) : void 0;
       if (enabled && !await this.checkInterpolationSupport(size, token)) {
         token.ensureCurrent();
@@ -6838,7 +7728,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);
       }
@@ -6899,9 +7788,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyRemoteVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _364 => _364.remoteVideoStatisticsListener, 'optionalCall', _365 => _365(this.remoteVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _494 => _494.remoteVideoStatisticsListener, 'optionalCall', _495 => _495(this.remoteVideoStatistics)])).catch(() => {
       });
-    } catch (e20) {
+    } catch (e25) {
     }
   }
   /**
@@ -6916,9 +7805,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyNetworkStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _366 => _366.networkStatisticsListener, 'optionalCall', _367 => _367(this.networkStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _496 => _496.networkStatisticsListener, 'optionalCall', _497 => _497(this.networkStatistics)])).catch(() => {
       });
-    } catch (e21) {
+    } catch (e26) {
     }
   }
   /**
@@ -6936,9 +7825,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   notifyLocalVideoStatistics() {
     try {
-      void Promise.resolve(_optionalChain([this, 'access', _368 => _368.localVideoStatisticsListener, 'optionalCall', _369 => _369(this.localVideoStatistics)])).catch(() => {
+      void Promise.resolve(_optionalChain([this, 'access', _498 => _498.localVideoStatisticsListener, 'optionalCall', _499 => _499(this.localVideoStatistics)])).catch(() => {
       });
-    } catch (e22) {
+    } catch (e27) {
     }
   }
   /**
@@ -6999,6 +7888,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "media" /* media */,
       void 0,
       async (token) => {
+        this.ensureNoLocalSource();
         await this.coordinator.commit(
           new RealtimeState({
             connectionState: "Preparing" /* preparing */
@@ -7009,7 +7899,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         const completeCamera = this.launchTimer.startCamera();
         this.clearVideoStatistics();
         this.disposePermissionWatch();
-        const permissionWatch = await watchMediaPermissionPrompt(_nullishCoalesce(_optionalChain([options, 'optionalAccess', _370 => _370.useMicrophone]), () => ( false)));
+        const permissionWatch = await watchMediaPermissionPrompt(_nullishCoalesce(_optionalChain([options, 'optionalAccess', _500 => _500.useMicrophone]), () => ( false)));
         if (permissionWatch) {
           const completePermission = this.launchTimer.startPermission();
           void permissionWatch.decided.then(() => completePermission()).catch(() => {
@@ -7026,7 +7916,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           throw error;
         }
         token.ensureCurrent();
-        this.generationVideoFormat = _optionalChain([stream, 'access', _371 => _371.videoTrack, 'optionalAccess', _372 => _372.videoFormat]);
+        this.generationVideoFormat = _optionalChain([stream, 'access', _501 => _501.videoTrack, 'optionalAccess', _502 => _502.videoFormat]);
         completeCamera();
         this.cameraController.setPreviewReadyHandler((isCurrent) => {
           void this.coordinator.localPreviewDidBecomeReady(isCurrent);
@@ -7035,25 +7925,82 @@ 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 = _optionalChain([stream, 'access', _503 => _503.videoTrack, 'optionalAccess', _504 => _504.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 = _optionalChain([stream, 'access', _505 => _505.videoTrack, 'optionalAccess', _506 => _506.videoFormat]);
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 当前 Manager 拥有的媒体源轨道。
+   */
+  get currentLocalTrack() {
+    return _nullishCoalesce(_nullishCoalesce(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");
+    }
+  }
   /**
    * 移除媒体权限弹窗观察；授权决定已记录或不再需要观察时调用。
    */
   disposePermissionWatch() {
-    _optionalChain([this, 'access', _373 => _373.permissionWatchDispose, 'optionalCall', _374 => _374()]);
+    _optionalChain([this, 'access', _507 => _507.permissionWatchDispose, 'optionalCall', _508 => _508()]);
     this.permissionWatchDispose = void 0;
   }
   /**
    * 应用完整的上行视频格式，成功后更新本地轨道元数据，不改变生成格式或生命周期。
    * 复用配置操作准入，避免与建连、切换摄像头或其他配置更新并发。
    *
-   * @throws 无本地相机流、参数无效、操作冲突或底层编码更新失败时抛错。
+   * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
   async updateVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const track = this.cameraController.currentTrack;
-      const previousFormat = _optionalChain([track, 'optionalAccess', _375 => _375.videoFormat]);
+      const track = _nullishCoalesce(this.localVideoController.currentTrack, () => ( this.cameraController.currentTrack));
+      const previousFormat = _optionalChain([track, 'optionalAccess', _509 => _509.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);
@@ -7066,6 +8013,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 停止本地相机流并释放本地预览与 RTC 资源。
    */
   async stopLocalCameraStream() {
+    if (this.networkVideoController.currentTrack || this.localVideoController.isActive) {
+      return;
+    }
     await this.coordinator.run(
       "media" /* media */,
       void 0,
@@ -7106,11 +8056,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   /**
    * 使用当前 Manager 创建的本地流建立实时连接。
    *
-   * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
+   * 创建实时会话、加入 RTC 房间并启动会话心跳；摄像头源发布本地流，网络视频源仅接收。
    * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
    * 返回的远端媒体流在生成开始后承载远端生成画面。
    *
-   * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+   * @param localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
    * @returns 远端生成结果占位的媒体流。
    * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
    * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -7137,7 +8087,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
    * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
    *
-   * @param options.localStream 由 `createLocalCameraStream` 创建的本地媒体流。
+   * @param options.localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
    * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
    * @returns 承载远端生成画面的媒体流。
    * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
@@ -7149,7 +8099,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"
@@ -7171,7 +8121,12 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           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 +8138,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 断开实时连接并保留当前本地媒体预览。
    */
   async disconnect() {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     this.clearVideoStatistics();
     await this.coordinator.disconnect();
@@ -7192,6 +8148,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 关闭期间重复调用会等待同一个释放任务；关闭完成后仍可重新创建本地流。
    */
   async close() {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     this.clearVideoStatistics();
     await this.coordinator.terminate(1 /* all */);
@@ -7205,7 +8162,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 +8180,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();
         });
@@ -7235,7 +8192,8 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         localTrack,
         remoteVideoFormat: this.generationVideoFormat,
         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;
@@ -7270,6 +8228,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       context,
       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
@@ -7283,6 +8246,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       new RealtimeState({ connectionState: "Generating" /* generating */, sessionID, taskID }),
       token
     );
+    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 +8270,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 统一清理顺序：停止心跳与生成，再断开连接；all 额外释放本地媒体。
    */
   async performCleanup(scope, taskID) {
+    this.localVideoController.pause();
     this.launchTimer.cancel();
     this.remoteFrameDisplayHandler = void 0;
     this.clearVideoStatistics();
@@ -7309,20 +8281,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
     };
   }
   /**
@@ -7384,6 +8366,405 @@ var XmaxConfiguration = class {
   }
 };
 
+// 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 = _optionalChain([options, 'access', _510 => _510.model, 'optionalAccess', _511 => _511.trim, 'call', _512 => _512()]);
+    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 = _nullishCoalesce(options.pageNumber, () => ( 1));
+    const pageSize = _nullishCoalesce(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 (e28) {
+    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 (!_optionalChain([uid, 'optionalAccess', _513 => _513.trim, 'call', _514 => _514()]) || !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 {
+  /**
+   * 使用 API 错误分类，不虚构服务端未返回的业务错误码。
+   */
+  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) {
+    /**
+     * 服务层组件
+     */
+    __publicField(this, "tasks");
+    this.tasks = tasks;
+  }
+  /**
+   * 单次提交任务，不自动重试可能已扣费的请求。
+   */
+  submitTask(options) {
+    return this.tasks.submitTask(options);
+  }
+  /**
+   * 取得任务快照，不把服务端失败终态当成查询失败。
+   */
+  getTask(taskUid, options) {
+    return this.tasks.getTask(taskUid, _optionalChain([options, 'optionalAccess', _515 => _515.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 = _nullishCoalesce(options.intervalMs, () => ( 2e3));
+    const retries = _nullishCoalesce(options.maxConsecutiveRetries, () => ( 3));
+    validateDelay(interval);
+    if (options.timeoutMs !== void 0) {
+      validateDelay(options.timeoutMs);
+    }
+    if (!Number.isSafeInteger(retries) || retries < 0) {
+      throw new XmaxError(
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        "Retry count must be a non-negative integer"
+      );
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort();
+    _optionalChain([options, 'access', _516 => _516.signal, 'optionalAccess', _517 => _517.addEventListener, 'call', _518 => _518("abort", abort, { once: true })]);
+    if (_optionalChain([options, 'access', _519 => _519.signal, 'optionalAccess', _520 => _520.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(_optionalChain([options, 'access', _521 => _521.onTaskUpdated, 'optionalCall', _522 => _522(task)])).catch(() => {
+          });
+        } catch (e29) {
+        }
+        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);
+      _optionalChain([options, 'access', _523 => _523.signal, 'optionalAccess', _524 => _524.removeEventListener, 'call', _525 => _525("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 */ && (_nullishCoalesce(error.httpStatus, () => ( 0))) >= 500 && (error.apiCode === void 0 || error.apiCode === error.httpStatus);
+}
+function isResultAvailable(task) {
+  const result = task.result;
+  if (!_optionalChain([result, 'optionalAccess', _526 => _526.url, 'optionalAccess', _527 => _527.trim, 'call', _528 => _528()]) || _optionalChain([result, 'access', _529 => _529.uploadError, 'optionalAccess', _530 => _530.trim, 'call', _531 => _531()]) || 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 (e30) {
+    return false;
+  }
+}
+
 // src/Core/XmaxClient.ts
 var XmaxClient = class {
   /**
@@ -7429,6 +8810,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 +8832,7 @@ var XmaxClient = class {
   /**
    * 创建文件存储 Service。
    *
-   * @returns 可上传图片到对象存储的存储 Service，返回地址可用作参考图路径。
+   * @returns 可上传图片和视频到对象存储的存储 Service。
    */
   createStorageService() {
     return new StorageService({ apiService: this.apiService });
@@ -7452,45 +8844,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 = _nullishCoalesce(init.provider, () => ( "trtc")) /* trtc */;
+    const providers = supportedRtcProviders(init.model);
+    this.provider = _nullishCoalesce(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 = _nullishCoalesce(_optionalChain([init, 'access', _376 => _376.frameInterpolation, 'optionalAccess', _377 => _377.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 = _nullishCoalesce(_nullishCoalesce(_optionalChain([init, 'access', _378 => _378.frameInterpolation, 'optionalAccess', _379 => _379.enabled]), () => ( init.isFrameInterpolationEnabled)), () => ( false));
-    this.frameInterpolation = Object.freeze({ enabled: this.isFrameInterpolationEnabled, targetFrameRate });
+    this.model = init.model;
+    this.isFrameInterpolationEnabled = _nullishCoalesce(init.isFrameInterpolationEnabled, () => ( false));
   }
 };
 
@@ -7501,29 +8884,6 @@ var VideoContentMode = /* @__PURE__ */ ((VideoContentMode2) => {
   return VideoContentMode2;
 })(VideoContentMode || {});
 
-// src/Service/Realtime/RealtimeContext.ts
-var RealtimeContext = class {
-  /**
-   * 创建实时生成条件并规范化文本和参考路径。
-   */
-  constructor(init) {
-    /**
-     * 生成条件
-     */
-    /**
-     * 实时生成使用的文本条件。
-     */
-    __publicField(this, "prompt");
-    /**
-     * 已上传参考图片的可选远端路径。
-     */
-    __publicField(this, "referencePath");
-    this.prompt = init.prompt.trim();
-    const normalizedReferencePath = _optionalChain([init, 'access', _380 => _380.referencePath, 'optionalAccess', _381 => _381.trim, 'call', _382 => _382()]);
-    this.referencePath = normalizedReferencePath || void 0;
-  }
-};
-
 // ../../node_modules/.pnpm/framegen@1.4.0/node_modules/framegen/rt.js
 var WG = 8;
 var texBgSeq = 0;
@@ -9516,11 +10876,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 +10891,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();
@@ -9646,11 +11006,11 @@ var _FrameInterpolationManager = class _FrameInterpolationManager {
     if (this.destroyed) return;
     this.destroyed = true;
     this.device.removeEventListener("uncapturederror", this.onGPUError);
-    _optionalChain([this, 'access', _383 => _383.runtime, 'optionalAccess', _384 => _384.destroy, 'call', _385 => _385()]);
+    _optionalChain([this, 'access', _532 => _532.runtime, 'optionalAccess', _533 => _533.destroy, 'call', _534 => _534()]);
     this.runtime = void 0;
     this.textures.forEach((texture) => texture.destroy());
     this.textures = [];
-    _optionalChain([this, 'access', _386 => _386.context, 'optionalAccess', _387 => _387.unconfigure, 'call', _388 => _388()]);
+    _optionalChain([this, 'access', _535 => _535.context, 'optionalAccess', _536 => _536.unconfigure, 'call', _537 => _537()]);
     this.device.destroy();
   }
 };
@@ -9659,6 +11019,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);
@@ -9753,7 +11114,9 @@ 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);
   }
   /** 帧按显示时间升序入队；同一时间的内容后到先出。 */
@@ -9829,7 +11192,7 @@ var RemoteVideoFramePipeline = class {
   setActive(active) {
     if (active === this.active) return;
     this.active = active;
-    _optionalChain([this, 'access', _389 => _389.options, 'access', _390 => _390.onActiveChange, 'optionalCall', _391 => _391(active)]);
+    _optionalChain([this, 'access', _538 => _538.options, 'access', _539 => _539.onActiveChange, 'optionalCall', _540 => _540(active)]);
   }
   resetTimeline() {
     this.generation++;
@@ -9860,7 +11223,7 @@ var RemoteVideoFramePipeline = class {
     this.callback = void 0;
     clearTimeout(this.initializationTimer);
     this.resetTimeline();
-    _optionalChain([this, 'access', _392 => _392.processor, 'optionalAccess', _393 => _393.destroy, 'call', _394 => _394()]);
+    _optionalChain([this, 'access', _541 => _541.processor, 'optionalAccess', _542 => _542.destroy, 'call', _543 => _543()]);
     this.processor = void 0;
   }
 };
@@ -9918,7 +11281,7 @@ var XmaxVideoView = class {
      * DOM 挂载状态
      */
     __publicField(this, "detached", false);
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _395 => _395.videoContentMode]), () => ( "fill")) /* fill */;
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _544 => _544.videoContentMode]), () => ( "fill")) /* fill */;
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -9992,14 +11355,14 @@ 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) {
+    if ((this.videoElement.srcObject || this.videoElement.getAttribute("src")) && !this.hasNotifiedFrameDisplay) {
       this.armFrameDisplayNotification();
     }
   }
@@ -10010,8 +11373,29 @@ var XmaxVideoView = class {
     this.detached = true;
     this.stopInterpolation();
     this.cancelFrameDisplayNotification();
+    if (this.videoElement.getAttribute("src")) {
+      this.videoElement.pause();
+    }
     this.element.remove();
   }
+  /**
+   * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
+   */
+  setVideoURL(url) {
+    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();
+  }
   /**
    * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
    */
@@ -10024,6 +11408,7 @@ var XmaxVideoView = class {
     this.hasNotifiedFrameDisplay = false;
     this.videoElement.srcObject = stream;
     if (stream) {
+      this.videoElement.autoplay = true;
       this.armFrameDisplayNotification();
       this.startInterpolation();
     }
@@ -10065,8 +11450,8 @@ var XmaxVideoView = class {
   stopInterpolation() {
     const pipeline = this.interpolationPipeline;
     this.interpolationPipeline = void 0;
-    _optionalChain([pipeline, 'optionalAccess', _396 => _396.stop, 'call', _397 => _397()]);
-    _optionalChain([this, 'access', _398 => _398.interpolationCanvas, 'optionalAccess', _399 => _399.remove, 'call', _400 => _400()]);
+    _optionalChain([pipeline, 'optionalAccess', _545 => _545.stop, 'call', _546 => _546()]);
+    _optionalChain([this, 'access', _547 => _547.interpolationCanvas, 'optionalAccess', _548 => _548.remove, 'call', _549 => _549()]);
     this.interpolationCanvas = void 0;
   }
   /**
@@ -10092,11 +11477,14 @@ var XmaxVideoView = class {
   detachCurrentTrack() {
     const track = this.currentTrack;
     if (track) {
-      _optionalChain([VideoRenderRegistry, 'access', _401 => _401.binding, 'call', _402 => _402(track), 'optionalAccess', _403 => _403.detachHandler, 'call', _404 => _404(this)]);
+      _optionalChain([VideoRenderRegistry, 'access', _550 => _550.binding, 'call', _551 => _551(track), 'optionalAccess', _552 => _552.detachHandler, 'call', _553 => _553(this)]);
     }
     this.setFrameInterpolation(void 0);
     this.cancelFrameDisplayNotification();
     this.videoElement.srcObject = null;
+    if (this.videoElement.getAttribute("src")) {
+      this.setVideoURL(null);
+    }
   }
   /**
    * 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。
@@ -10112,8 +11500,8 @@ var XmaxVideoView = class {
       }
       this.hasNotifiedFrameDisplay = true;
       this.cancelFrameDisplayNotification();
-      _optionalChain([binding, 'optionalAccess', _405 => _405.frameDisplayHandler, 'optionalCall', _406 => _406()]);
-      _optionalChain([this, 'access', _407 => _407.frameDisplayHandler, 'optionalCall', _408 => _408()]);
+      _optionalChain([binding, 'optionalAccess', _554 => _554.frameDisplayHandler, 'optionalCall', _555 => _555()]);
+      _optionalChain([this, 'access', _556 => _556.frameDisplayHandler, 'optionalCall', _557 => _557()]);
     };
     if (typeof this.videoElement.requestVideoFrameCallback === "function") {
       this.videoFrameCallbackID = this.videoElement.requestVideoFrameCallback(notify);
@@ -10183,9 +11571,9 @@ var XmaxRealtimeVideoView = class {
     __publicField(this, "currentLocalTrack");
     __publicField(this, "currentRemoteTrack");
     __publicField(this, "contentMode");
-    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _409 => _409.videoContentMode]), () => ( "fill")) /* fill */;
-    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _410 => _410.localTrack]);
-    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _411 => _411.remoteTrack]);
+    this.contentMode = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _558 => _558.videoContentMode]), () => ( "fill")) /* fill */;
+    this.currentLocalTrack = _optionalChain([options, 'optionalAccess', _559 => _559.localTrack]);
+    this.currentRemoteTrack = _optionalChain([options, 'optionalAccess', _560 => _560.remoteTrack]);
     this.element = document.createElement("div");
     this.element.style.position = "relative";
     this.element.style.overflow = "hidden";
@@ -10344,5 +11732,11 @@ var XmaxRealtimeVideoView = class {
 
 
 
-exports.XmaxEnvironment = XmaxEnvironment; exports.apiBaseURL = apiBaseURL; exports.XmaxLoggerOption = XmaxLoggerOption; exports.XmaxLogger = XmaxLogger; exports.XmaxErrorCode = XmaxErrorCode; exports.XmaxError = XmaxError; exports.RealtimeVideoEncoderPreference = RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = RealtimeVideoFormat; exports.RealtimeModel = RealtimeModel; exports.defaultFrameRate = defaultFrameRate; exports.defaultCameraVideoFormat = defaultCameraVideoFormat; exports.MediaService = MediaService; exports.StoredFile = StoredFile; exports.StorageService = StorageService; exports.CameraPosition = CameraPosition; exports.RtcProvider = RtcProvider; exports.RealtimeVideoTrack = RealtimeVideoTrack; exports.RealtimeMediaStream = RealtimeMediaStream; exports.RealtimeConnectionState = RealtimeConnectionState; exports.RealtimeReason = RealtimeReason; exports.RealtimeState = RealtimeState; exports.XmaxConfiguration = XmaxConfiguration; exports.XmaxClient = XmaxClient; exports.RealtimeConfiguration = RealtimeConfiguration; exports.VideoContentMode = VideoContentMode; exports.RealtimeContext = RealtimeContext; exports.XmaxVideoView = XmaxVideoView; exports.XmaxRealtimeVideoView = XmaxRealtimeVideoView;
-//# sourceMappingURL=chunk-FEL5MJMJ.cjs.map
+
+
+
+
+
+
+exports.XmaxEnvironment = XmaxEnvironment; exports.apiBaseURL = apiBaseURL; exports.XmaxLoggerOption = XmaxLoggerOption; exports.XmaxLogger = XmaxLogger; exports.XmaxErrorCode = XmaxErrorCode; exports.XmaxError = XmaxError; exports.RealtimeVideoEncoderPreference = RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = RealtimeVideoFormat; exports.RtcProvider = RtcProvider; exports.RealtimeModel = RealtimeModel; exports.modelDisplayName = modelDisplayName; exports.defaultFrameRate = defaultFrameRate; exports.defaultCameraVideoFormat = defaultCameraVideoFormat; exports.supportedRtcProviders = supportedRtcProviders; exports.MediaService = MediaService; exports.StoredFile = StoredFile; exports.StorageService = StorageService; exports.CameraPosition = CameraPosition; exports.RealtimeVideoTrack = RealtimeVideoTrack; exports.RealtimeMediaStream = RealtimeMediaStream; exports.RealtimeVideoSampleMethod = RealtimeVideoSampleMethod; exports.RealtimeContext = RealtimeContext; exports.RealtimeConnectionState = RealtimeConnectionState; exports.RealtimeReason = RealtimeReason; exports.RealtimeState = RealtimeState; exports.XmaxConfiguration = XmaxConfiguration; exports.NonRealtimeQuality = NonRealtimeQuality; exports.NonRealtimeTaskStatus = NonRealtimeTaskStatus; exports.NonRealtimeTaskError = NonRealtimeTaskError; exports.XmaxClient = XmaxClient; exports.RealtimeConfiguration = RealtimeConfiguration; exports.VideoContentMode = VideoContentMode; exports.XmaxVideoView = XmaxVideoView; exports.XmaxRealtimeVideoView = XmaxRealtimeVideoView;
+//# sourceMappingURL=chunk-JN6HURTT.cjs.map