@xmaxai/web-sdk 1.0.4 → 1.0.5

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

@@ -12,9 +12,16 @@ var API_BASE_URLS = {
   ["china" /* china */]: "https://cloud.xmax.22duck.cn/open/api/v1",
   ["global" /* global */]: "https://api.xmax.cloud/open/api/v1"
 };
+var NON_REALTIME_API_BASE_URLS = {
+  ["china" /* china */]: "https://api.xmaxai.com/open/api/v1",
+  ["global" /* global */]: "https://api.xmax.ai/open/api/v1"
+};
 function apiBaseURL(environment) {
   return API_BASE_URLS[environment];
 }
+function nonRealtimeApiBaseURL(environment) {
+  return NON_REALTIME_API_BASE_URLS[environment];
+}
 
 // src/Foundation/Logging/XmaxLogger.ts
 var XmaxLoggerOption = /* @__PURE__ */ ((XmaxLoggerOption2) => {
@@ -198,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.4";
+var XMAX_SDK_VERSION = "1.0.5";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -268,8 +275,24 @@ var _ApiService = class _ApiService {
    */
   async request(method, path, body, options) {
     this.validateConfiguration();
+    if (options?.signal?.aborted) {
+      throw new XmaxError("CANCELLED" /* cancelled */, "API request was cancelled");
+    }
     const request = this.makeRequest(method, path, body, options);
     const startedAt = Date.now();
+    const timeoutSignal = request.init.signal;
+    const controller = new AbortController();
+    const abortTimeout = () => controller.abort(timeoutSignal.reason);
+    const abortCaller = () => controller.abort(new DOMException("Cancelled", "AbortError"));
+    timeoutSignal.addEventListener("abort", abortTimeout, { once: true });
+    options?.signal?.addEventListener("abort", abortCaller, { once: true });
+    request.init.signal = controller.signal;
+    if (timeoutSignal.aborted) {
+      abortTimeout();
+    }
+    if (options?.signal?.aborted) {
+      abortCaller();
+    }
     let status;
     let text;
     try {
@@ -280,6 +303,9 @@ var _ApiService = class _ApiService {
       const mapped = _ApiService.transportError(error);
       this.logFailure(method, path, mapped, startedAt);
       throw mapped;
+    } finally {
+      timeoutSignal.removeEventListener("abort", abortTimeout);
+      options?.signal?.removeEventListener("abort", abortCaller);
     }
     try {
       const value = _ApiService.parseResponse(text, status);
@@ -297,8 +323,8 @@ var _ApiService = class _ApiService {
   /**
    * 发送 GET 请求。
    */
-  get(path) {
-    return this.request("GET" /* get */, path);
+  get(path, options) {
+    return this.request("GET" /* get */, path, void 0, options);
   }
   /**
    * 发送 POST 请求。
@@ -405,7 +431,8 @@ var _ApiService = class _ApiService {
       });
     }
     const ok = status >= 200 && status < 300;
-    if (!ok || envelope.success !== true) {
+    const succeeded = envelope.success === true || envelope.success === void 0 && envelope.code === 200;
+    if (!ok || !succeeded) {
       const message = envelope.message?.trim();
       throw new XmaxError(
         "API_ERROR" /* apiError */,
@@ -561,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) {
@@ -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,6 +909,81 @@ var StorageService = class _StorageService {
    * 上传图片并返回访问地址。
    */
   async uploadImage(options) {
+    return this.upload(options, "Image");
+  }
+  /**
+   * 普通上传原始视频并返回访问地址，不进行转码、压缩或分片。
+   */
+  async uploadVideo(options) {
+    return this.upload(options, "Video");
+  }
+  /**
+   * 下载原始视频文件并交给浏览器保存，支持取消网络下载。
+   */
+  async downloadVideo(options) {
+    const fileName = _StorageService.validateFileName(options.fileName);
+    let url;
+    try {
+      url = new URL(options.url.trim());
+    } catch {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Invalid video download URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video download requires an HTTP(S) URL without embedded credentials");
+    }
+    if (typeof document === "undefined" || !document.body) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video saving requires a browser document");
+    }
+    let objectURL;
+    let link;
+    let saveRequested = false;
+    try {
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      const response = await fetch(options.url.trim(), { credentials: "omit", signal: options.signal });
+      if (!response.ok) {
+        throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, "Video download failed", { httpStatus: response.status });
+      }
+      const data = await response.blob();
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      if (data.size === 0) {
+        throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, "Downloaded video is empty");
+      }
+      objectURL = URL.createObjectURL(data);
+      link = document.createElement("a");
+      link.href = objectURL;
+      link.download = fileName;
+      link.hidden = true;
+      document.body.appendChild(link);
+      link.click();
+      saveRequested = true;
+    } catch (error) {
+      if (options.signal?.aborted) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Video download was cancelled");
+      }
+      if (error instanceof XmaxError) {
+        throw error;
+      }
+      throw new XmaxError("DOWNLOAD_ERROR" /* downloadError */, error instanceof Error ? error.message : String(error));
+    } finally {
+      link?.remove();
+      if (objectURL) {
+        const resourceURL = objectURL;
+        if (saveRequested) {
+          setTimeout(() => URL.revokeObjectURL(resourceURL), 6e4);
+        } else {
+          URL.revokeObjectURL(resourceURL);
+        }
+      }
+    }
+  }
+  /**
+   * 获取临时凭证并通过 COS putObject 上传文件，统一处理进度、结果和错误。
+   */
+  async upload(options, mediaType) {
     const startedAt = Date.now();
     try {
       const safeName = _StorageService.validateFileName(options.fileName);
@@ -844,7 +992,7 @@ var StorageService = class _StorageService {
       if (body.size === 0) {
         throw new XmaxError(
           "INVALID_CONFIGURATION" /* invalidConfiguration */,
-          "Image data cannot be empty"
+          `${mediaType} data cannot be empty`
         );
       }
       const temporary = await this.fetchStorageConfiguration();
@@ -982,7 +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;
@@ -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);
     /**
@@ -1267,12 +1417,15 @@ var _AgoraRtcManager = class _AgoraRtcManager {
   async destroy() {
     this.lifecycle++;
     const client = this.client;
-    this.listener = void 0;
     this.clearRoom();
     this.client = void 0;
     client?.removeAllListeners();
     this.camera?.close();
     this.microphone?.close();
+    this.externalVideo?.close();
+    this.externalAudio?.close();
+    this.externalVideo = void 0;
+    this.externalAudio = void 0;
     this.camera = void 0;
     this.microphone = void 0;
     const sdk = this.sdk;
@@ -1291,7 +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({
@@ -1326,11 +1481,42 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     camera?.close();
   }
   /**
-   * 应用公共编码配置，补偿移动端竖屏的宽高转置。
+   * 将外部原生轨包装为 Agora 本地轨，不申请设备权限；失败时释放本次克隆。
+   */
+  async setExternalMediaTracks(tracks) {
+    this.requireClient();
+    if (this.camera || this.microphone || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
+    }
+    if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media requires live video and optional audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    let audio;
+    let wrappedVideo;
+    let wrappedAudio;
+    try {
+      audio = tracks.audioTrack?.clone();
+      wrappedVideo = this.sdk.createCustomVideoTrack({ mediaStreamTrack: video });
+      if (audio) {
+        wrappedAudio = this.sdk.createCustomAudioTrack({ mediaStreamTrack: audio, encoderConfig: "music_standard" });
+      }
+      this.externalVideo = wrappedVideo;
+      this.externalAudio = wrappedAudio;
+    } catch (error) {
+      wrappedVideo?.close();
+      wrappedAudio?.close();
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
+  }
+  /**
+   * 应用公共编码配置；仅相机源补偿移动端转置，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,
@@ -1349,7 +1535,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     await this.rejoinTask?.catch(() => {
     });
     const client = this.requireClient();
-    if (configuration.provider !== "agora" || this.connection) {
+    if (configuration.provider !== "agora" /* agora */ || this.connection) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Agora credentials and an idle room are required");
     }
     const version = ++this.roomVersion;
@@ -1385,7 +1571,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     if (signal?.aborted) throw this.cancelled();
     const current = this.connection;
     const client = this.requireClient();
-    if (!current || config.provider !== "agora" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+    if (!current || config.provider !== "agora" /* agora */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "Agora session binding changed");
     }
     const version = this.roomVersion;
@@ -1454,12 +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 = 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 = 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));
+    }
   }
   /**
    * 订阅远端主视频并返回原生轨道，不创建额外播放视图。
@@ -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 = 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 {
   /**
@@ -2072,6 +2275,11 @@ var TrtcRtcManager = class {
      */
     __publicField(this, "isCapturing", false);
     __publicField(this, "isAudioCapturing", false);
+    /**
+     * 外部媒体的克隆轨；原始轨道由媒体源管理。
+     */
+    __publicField(this, "externalVideo");
+    __publicField(this, "externalAudio");
     /**
      * 房间状态
      */
@@ -2106,13 +2314,18 @@ var TrtcRtcManager = class {
   async destroy() {
     const lease = this.lease;
     this.lease = void 0;
-    this.eventListener = void 0;
+    const externalVideo = this.externalVideo;
+    const externalAudio = this.externalAudio;
+    this.externalVideo = void 0;
+    this.externalAudio = void 0;
     this.isCapturing = false;
     this.isAudioCapturing = false;
     this.isInRoom = false;
     this.removeStatsListeners?.();
     this.removeStatsListeners = void 0;
     if (!lease) {
+      externalVideo?.stop();
+      externalAudio?.stop();
       return;
     }
     try {
@@ -2123,8 +2336,56 @@ var TrtcRtcManager = class {
       await lease.engine.stopLocalVideo();
     } catch {
     }
+    externalVideo?.stop();
+    externalAudio?.stop();
     this.engineManager.release(lease);
   }
+  /**
+   * 准备外部音视频轨但不发布；失败时释放克隆轨，不影响原始媒体源。
+   */
+  async setExternalMediaTracks(tracks) {
+    const engine = this.requireEngine();
+    if (this.isCapturing || this.isAudioCapturing || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
+    }
+    if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media tracks must be live video/audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    this.externalVideo = video;
+    let audio;
+    try {
+      audio = tracks.audioTrack?.clone();
+      this.externalAudio = audio;
+      await engine.startLocalVideo({ publish: false, option: { videoTrack: video } });
+      if (this.lease?.engine !== engine) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
+      }
+      if (audio) {
+        await engine.startLocalAudio({
+          publish: false,
+          option: { audioTrack: audio, echoCancellation: false, autoGainControl: false, noiseSuppression: false }
+        });
+        if (this.lease?.engine !== engine) {
+          throw new XmaxError("CANCELLED" /* cancelled */, "External media preparation was cancelled");
+        }
+      }
+    } catch (error) {
+      if (this.lease?.engine === engine) {
+        await engine.stopLocalAudio().catch(() => {
+        });
+        await engine.stopLocalVideo().catch(() => {
+        });
+      }
+      if (this.externalVideo === video) {
+        this.externalVideo = void 0;
+        this.externalAudio = void 0;
+      }
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
+  }
   /**
    * 启动摄像头采集（不发布）。
    *
@@ -2133,7 +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,6 +2464,9 @@ var TrtcRtcManager = class {
    * 停止摄像头采集；引擎未初始化或采集未启动时不产生效果。
    */
   async stopCameraCapture() {
+    if (this.externalVideo) {
+      return;
+    }
     const engine = this.lease?.engine;
     this.isCapturing = false;
     if (!engine) {
@@ -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();
@@ -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 {
@@ -2330,7 +2594,7 @@ var TrtcRtcManager = class {
    */
   async unpublishLocalVideo() {
     const engine = this.lease?.engine;
-    if (!engine || !this.isCapturing) {
+    if (!engine || !this.isCapturing && !this.externalVideo) {
       return;
     }
     try {
@@ -2340,14 +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 {
@@ -2362,7 +2630,7 @@ var TrtcRtcManager = class {
    */
   async unpublishLocalAudio() {
     const engine = this.lease?.engine;
-    if (!engine || !this.isAudioCapturing) {
+    if (!engine || !this.isAudioCapturing && !this.externalAudio) {
       return;
     }
     try {
@@ -2540,19 +2808,19 @@ var TrtcRtcManager = class {
       source.off(RTC_EVENT.networkQuality, onNetworkQuality);
     };
     source.on(RTC_EVENT.remoteVideoAvailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (this.lease?.engine !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
       this.eventListener?.onRemoteVideoPublished(event.userId, true);
     });
     source.on(RTC_EVENT.remoteVideoUnavailable, (event) => {
-      if (event.streamType !== STREAM_TYPE_MAIN) {
+      if (this.lease?.engine !== engine || event.streamType !== STREAM_TYPE_MAIN) {
         return;
       }
       this.eventListener?.onRemoteVideoPublished(event.userId, false);
     });
     source.on(RTC_EVENT.customMessage, (event) => {
-      if (event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
+      if (this.lease?.engine !== engine || event.cmdId !== CUSTOM_MESSAGE_CMD_ID) {
         return;
       }
       let message;
@@ -2645,6 +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;
     engine?.removeAllListeners();
-    if (engine && sdk) sdk.default.destroyEngine(engine);
+    try {
+      if (engine && sdk) sdk.default.destroyEngine(engine);
+    } finally {
+      this.externalVideo?.stop();
+      this.externalAudio?.stop();
+      this.externalVideo = void 0;
+      this.externalAudio = void 0;
+    }
+  }
+  /**
+   * 将克隆的文件音视频轨绑定到主流，不采集设备、不自动发布。
+   */
+  async setExternalMediaTracks(tracks) {
+    const engine = this.requireEngine();
+    const sdk = this.sdk;
+    if (this.camera || this.microphone || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
+    }
+    if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External media tracks must be live video/audio tracks");
+    }
+    const video = tracks.videoTrack.clone();
+    this.externalVideo = video;
+    let audio;
+    const index = sdk.StreamIndex.STREAM_INDEX_MAIN;
+    const ensureCurrent = () => {
+      if (this.engine !== engine || this.externalVideo !== video) {
+        throw this.cancelled();
+      }
+    };
+    try {
+      audio = tracks.audioTrack?.clone();
+      this.externalAudio = audio;
+      await engine.setVideoSourceType(index, sdk.VideoSourceType.VIDEO_SOURCE_TYPE_EXTERNAL);
+      ensureCurrent();
+      await engine.setExternalVideoTrack(index, video);
+      ensureCurrent();
+      if (audio) {
+        await engine.setAudioSourceType(index, sdk.AudioSourceType.AUDIO_SOURCE_TYPE_EXTERNAL);
+        ensureCurrent();
+        await engine.setExternalAudioTrack(index, audio);
+        ensureCurrent();
+      }
+    } catch (error) {
+      if (this.engine === engine) {
+        await engine.setAudioSourceType(index, sdk.AudioSourceType.AUDIO_SOURCE_TYPE_INTERNAL).catch(() => {
+        });
+        await engine.setVideoSourceType(index, sdk.VideoSourceType.VIDEO_SOURCE_TYPE_INTERNAL).catch(() => {
+        });
+      }
+      if (this.externalVideo === video) {
+        this.externalVideo = void 0;
+        this.externalAudio = void 0;
+      }
+      video.stop();
+      audio?.stop();
+      throw this.mapError(error);
+    }
   }
   async startCameraCapture(options) {
     const engine = this.requireEngine();
-    if (this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is already running");
+    if (this.camera || this.externalVideo) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is already prepared");
+    }
     const version = ++this.captureVersion;
     await this.run(() => engine.setVideoEncoderConfig({
       ...rtcOrientedVideoSize({ width: options.width, height: options.height }),
@@ -2751,15 +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",
@@ -2772,7 +3108,7 @@ var VeRtcManager = class {
     await this.recovery?.catch(() => {
     });
     const engine = this.requireEngine();
-    if (config.provider !== "vertc" || config.appID !== VERTC_APP_ID || this.connection) {
+    if (config.provider !== "vertc" /* vertc */ || config.appID !== VERTC_APP_ID || this.connection) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "VeRTC credentials for the configured AppID and an idle room are required");
     }
     this.clearRoom();
@@ -2819,7 +3155,7 @@ var VeRtcManager = class {
     const engine = this.requireEngine();
     const current = this.connection;
     if (signal?.aborted) throw this.cancelled();
-    if (!current || config.provider !== "vertc" || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
+    if (!current || config.provider !== "vertc" /* vertc */ || config.appID !== current.appID || config.roomID !== current.roomID || config.userID !== current.userID) {
       throw new XmaxError("SESSION_ERROR" /* sessionError */, "VeRTC session binding changed");
     }
     const version = this.roomVersion;
@@ -2861,7 +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() {
@@ -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;
@@ -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");
   }
 }
 
@@ -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 {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an absolute HTTP or HTTPS URL");
+    }
+    if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Network video requires an HTTP or HTTPS URL without embedded credentials");
+    }
+    const sampleMethod = options.sampleMethod ?? "time" /* time */;
+    if (!Object.values(RealtimeVideoSampleMethod).includes(sampleMethod)) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported video sample method");
+    }
+    if (this.currentTrack) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current network video stream before creating another one");
+    }
+    options.videoFormat.validate();
+    const size = mediaService.resolveModelInputSize(options.videoFormat);
+    const track = new RealtimeVideoTrack({
+      id: "network-video",
+      videoFormat: options.videoFormat.resized(size.width, size.height)
+    });
+    this.currentTrack = track;
+    this.reference = Object.freeze({ path: options.url.trim(), sampleMethod });
+    this.onFinish = options.onFinish;
+    VideoRenderRegistry.register(track, {
+      attachHandler: (view) => this.attach(view),
+      detachHandler: (view) => this.detach(view)
+    });
+    return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+  }
+  /**
+   * 释放全部预览绑定及源信息，不影响其他媒体源。
+   */
+  stop() {
+    for (const view of this.bindings.keys()) {
+      this.detach(view);
+    }
+    if (this.currentTrack) {
+      VideoRenderRegistry.unregister(this.currentTrack);
+    }
+    this.currentTrack = void 0;
+    this.reference = void 0;
+    this.onFinish = void 0;
+    this.position = 0;
+    this.ended = false;
+  }
+  /**
+   * 绑定播放器，恢复预览位置；本地播放错误仅记录，不中断服务端生成。
+   */
+  attach(view) {
+    if (!this.reference || !view.videoElement || !view.setVideoURL) {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "This render target does not support network video preview");
+    }
+    this.detach(view);
+    const video = view.videoElement;
+    video.autoplay = !this.ended;
+    const restore = () => {
+      if (this.position > 0) {
+        video.currentTime = Math.min(this.position, Math.max(0, video.duration - 1e-3) || this.position);
+      }
+      if (this.ended) {
+        video.pause();
+      }
+    };
+    const fail = () => {
+      XmaxLogger.render.warning(() => "\u7F51\u7EDC\u89C6\u9891\u9884\u89C8\u5931\u8D25 (Network Video Preview Failed)");
+    };
+    video.addEventListener("loadedmetadata", restore);
+    video.addEventListener("error", fail);
+    this.bindings.set(view, () => {
+      this.position = video.currentTime;
+      this.ended = video.ended || this.ended;
+      video.removeEventListener("loadedmetadata", restore);
+      video.removeEventListener("error", fail);
+      view.setVideoURL?.(null);
+    });
+    view.isMirrored = false;
+    view.setVideoURL(this.reference.path);
+  }
+  /**
+   * 保存预览进度并释放该视图的地址和事件监听。
+   */
+  detach(view) {
+    this.bindings.get(view)?.();
+    this.bindings.delete(view);
+  }
+};
+
+// src/Media/Video/LocalVideoController.ts
+var LocalVideoController = class {
+  /**
+   * 保存媒体错误处理器，不创建浏览器资源。
+   */
+  constructor(onError = () => {
+  }) {
+    /**
+     * 当前文件资源与运行期错误通知
+     */
+    __publicField(this, "source");
+    __publicField(this, "onError");
+    this.onError = onError;
+  }
+  /**
+   * 是否持有文件资源，包含尚未完成准备的播放器。
+   */
+  get isActive() {
+    return this.source !== void 0;
+  }
+  /**
+   * 准备完成的本地视频轨。
+   */
+  get currentTrack() {
+    return this.source?.track;
+  }
+  /**
+   * 文件音频输出；禁用音频时为空，无音轨文件的 Web Audio 输出为静音。
+   */
+  get audioTrack() {
+    return this.source?.audioDestination?.stream.getAudioTracks()[0];
+  }
+  /**
+   * 校验文件和格式，准备首帧与音频输出；应从用户点击事件直接调用以解锁播放。
+   */
+  async create(options, mediaService, signal) {
+    if (this.source) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local video before creating another one");
+    }
+    if (!(options.file instanceof Blob) || options.file.size === 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video requires a non-empty File or Blob");
+    }
+    const format = this.resolveVideoFormat(options.videoFormat, mediaService);
+    if (signal.aborted) {
+      throw this.cancelled();
+    }
+    if (typeof document === "undefined") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Local video requires a browser");
+    }
+    const video = document.createElement("video");
+    const canvas = document.createElement("canvas");
+    const context = canvas.getContext("2d");
+    if (!context || typeof canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas video capture is unavailable");
+    }
+    canvas.width = format.width;
+    canvas.height = format.height;
+    const source = {
+      video,
+      canvas,
+      context,
+      url: URL.createObjectURL(options.file),
+      abort: new AbortController(),
+      targets: /* @__PURE__ */ new Set()
+    };
+    this.source = source;
+    try {
+      video.playsInline = true;
+      video.loop = options.loop ?? true;
+      video.preload = "auto";
+      video.volume = 1;
+      video.muted = options.includeAudio === false;
+      if (options.includeAudio !== false) {
+        if (typeof AudioContext === "undefined") {
+          throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Web Audio is unavailable; disable file audio or use a supported browser");
+        }
+        const audio = new AudioContext();
+        source.audioContext = audio;
+        source.audioSource = audio.createMediaElementSource(video);
+        source.audioDestination = audio.createMediaStreamDestination();
+        source.audioSource.connect(source.audioDestination);
+      }
+      video.src = source.url;
+      const resume = source.audioContext?.resume();
+      const playing = this.play(source, signal);
+      await this.wait(source, Promise.all([resume, playing]), signal);
+      video.pause();
+      if (!video.videoWidth || !video.videoHeight || !Number.isFinite(video.duration) || video.duration <= 0) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "The file has no playable finite video stream");
+      }
+      await this.rewind(source, signal);
+      this.draw(source);
+      source.stream = canvas.captureStream(format.fps);
+      const nativeTrack = source.stream.getVideoTracks()[0];
+      if (!nativeTrack) {
+        throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas did not provide a video track");
+      }
+      const track = new RealtimeVideoTrack({ id: "local-video", videoFormat: format });
+      track.mediaStreamTrack = nativeTrack;
+      source.track = track;
+      this.draw(source);
+      source.drawTimer = setInterval(() => {
+        if (this.source !== source) {
+          return;
+        }
+        try {
+          this.draw(source);
+        } catch {
+          this.handleError(source);
+        }
+      }, 1e3 / format.fps);
+      source.onError = () => this.handleError(source);
+      video.addEventListener("error", source.onError);
+      VideoRenderRegistry.register(track, {
+        attachHandler: (view) => {
+          view.isMirrored = false;
+          view.setMediaStream(source.stream);
+          source.targets.add(view);
+        },
+        detachHandler: (view) => {
+          source.targets.delete(view);
+          view.setMediaStream(null);
+        }
+      });
+      return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+    } catch (error) {
+      await this.stop();
+      throw XmaxError.from(error);
+    }
+  }
+  /**
+   * 开始信令发送成功后，从文件开头同步启动音视频；不等待远端首帧。
+   */
+  async start(signal) {
+    const source = this.source;
+    if (!source?.track) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is not prepared");
+    }
+    if (signal.aborted) {
+      throw this.cancelled();
+    }
+    try {
+      await this.rewind(source, signal);
+      await this.wait(source, Promise.all([source.audioContext?.resume(), this.play(source, signal)]), signal);
+    } catch (error) {
+      source.video.pause();
+      throw error;
+    }
+  }
+  /**
+   * 暂停文件音视频，保留当前预览；重新开始生成时回到文件开头。
+   */
+  pause() {
+    this.source?.video.pause();
+  }
+  /**
+   * 释放播放器、预览、定时器、轨道、音频上下文和对象 URL。
+   */
+  async stop() {
+    const source = this.source;
+    this.source = void 0;
+    if (!source) {
+      return;
+    }
+    source.abort.abort();
+    clearInterval(source.drawTimer);
+    if (source.onError) {
+      source.video.removeEventListener("error", source.onError);
+    }
+    if (source.track) {
+      VideoRenderRegistry.unregister(source.track);
+      source.track.mediaStreamTrack = void 0;
+    }
+    for (const view of source.targets) {
+      try {
+        view.setMediaStream(null);
+      } catch {
+      }
+    }
+    source.targets.clear();
+    source.video.pause();
+    source.video.removeAttribute("src");
+    source.video.load();
+    source.stream?.getTracks().forEach((track) => track.stop());
+    source.audioDestination?.stream.getTracks().forEach((track) => track.stop());
+    source.audioSource?.disconnect();
+    source.audioDestination?.disconnect();
+    URL.revokeObjectURL(source.url);
+    await source.audioContext?.close().catch(() => {
+    });
+  }
+  /**
+   * 播放被浏览器拒绝时给出可操作错误；关闭后的迟到播放立即暂停。
+   */
+  play(source, signal) {
+    return source.video.play().then(() => {
+      if (this.source !== source || source.abort.signal.aborted || signal.aborted) {
+        source.video.pause();
+        throw this.cancelled();
+      }
+    }).catch((error) => {
+      if (error instanceof XmaxError) {
+        throw error;
+      }
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Cannot play local video; call from a user click and use a browser-supported video codec");
+    });
+  }
+  /**
+   * 等待 seek 完成，确保重新生成从首帧开始，而非使用旧缓存画面。
+   */
+  async rewind(source, signal) {
+    if (source.video.currentTime === 0) {
+      return;
+    }
+    let seeked;
+    const ready = new Promise((resolve) => {
+      seeked = resolve;
+    });
+    source.video.addEventListener("seeked", seeked, { once: true });
+    try {
+      source.video.currentTime = 0;
+      await this.wait(source, ready, signal);
+    } finally {
+      source.video.removeEventListener("seeked", seeked);
+    }
+  }
+  /**
+   * 给浏览器准备和播放操作设置 10 秒上限，同时响应关闭、取消和解码错误。
+   */
+  wait(source, operation, signal) {
+    return new Promise((resolve, reject) => {
+      const finish = (error) => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+        source.abort.signal.removeEventListener("abort", abort);
+        source.video.removeEventListener("error", failed);
+        if (error) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+      const abort = () => finish(this.cancelled());
+      const failed = () => finish(new XmaxError("MEDIA_ERROR" /* mediaError */, "The browser cannot decode this video file"));
+      const timer = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Local video preparation timed out; start from a user click and check the video codec")), 1e4);
+      signal.addEventListener("abort", abort, { once: true });
+      source.abort.signal.addEventListener("abort", abort, { once: true });
+      source.video.addEventListener("error", failed, { once: true });
+      operation.then(() => finish(), finish);
+      if (signal.aborted || source.abort.signal.aborted) {
+        abort();
+      }
+    });
+  }
+  /**
+   * 等比缩放并居中补黑边，保留完整画面，不按设备方向转置文件尺寸。
+   */
+  draw(source) {
+    const { video, canvas, context } = source;
+    if (video.readyState < 2) {
+      return;
+    }
+    const scale = Math.min(canvas.width / video.videoWidth, canvas.height / video.videoHeight);
+    const width = video.videoWidth * scale;
+    const height = video.videoHeight * scale;
+    context.fillStyle = "black";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(video, (canvas.width - width) / 2, (canvas.height - height) / 2, width, height);
+  }
+  /**
+   * 仅为本地文件选择最接近宽高比的模型档位；比例距离相同时优先横屏。
+   * 无固定档位时保留公共尺寸解析规则，帧率和显式编码配置不变。
+   */
+  resolveVideoFormat(format, mediaService) {
+    format.validate();
+    const buckets = resolutionBuckets(mediaService.model);
+    let target = buckets.find((size2) => size2.width === format.width && size2.height === format.height);
+    if (!target && buckets.length > 0) {
+      const ratio = format.width / format.height;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      for (const bucket of buckets) {
+        const distance = Math.abs(Math.log(bucket.width / bucket.height / ratio));
+        const tied = Math.abs(distance - bestDistance) < 1e-9;
+        if (distance < bestDistance - 1e-9 || tied && bucket.width >= bucket.height && target && target.width < target.height) {
+          target = bucket;
+          bestDistance = distance;
+        }
+      }
+    }
+    const size = mediaService.resolveModelInputSize(target ?? format);
+    return format.resized(size.width, size.height);
+  }
+  /**
+   * 解码或绘制失败时停止媒体推进，并报告一次运行期错误。
+   */
+  handleError(source) {
+    if (this.source !== source || source.drawTimer === void 0) {
+      return;
+    }
+    clearInterval(source.drawTimer);
+    source.drawTimer = void 0;
+    source.video.pause();
+    XmaxLogger.realtime.warning(() => "\u672C\u5730\u89C6\u9891\u89E3\u7801\u5931\u8D25 (Local Video Decode Failed)");
+    this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "Local video decoding failed"));
+  }
+  /**
+   * 构造统一的媒体操作取消错误。
+   */
+  cancelled() {
+    return new XmaxError("CANCELLED" /* cancelled */, "Local video operation was cancelled");
+  }
+};
+
+// src/Service/Realtime/RealtimeContext.ts
+var RealtimeContext = class {
+  /**
+   * 创建实时生成条件并规范化文本和参考路径。
+   */
+  constructor(init) {
+    /**
+     * 服务端直接读取的网络视频。
+     */
+    __publicField(this, "referenceVideo");
+    /**
+     * 生成条件
+     */
+    /**
+     * 实时生成使用的文本条件。
+     */
+    __publicField(this, "prompt");
+    /**
+     * 已上传参考图片的可选远端路径。
+     */
+    __publicField(this, "referencePath");
+    this.referenceVideo = init.referenceVideo && Object.freeze({ ...init.referenceVideo });
+    this.prompt = init.prompt.trim();
+    const normalizedReferencePath = init.referencePath?.trim();
+    this.referencePath = normalizedReferencePath || void 0;
+  }
+};
+
 // src/Service/Realtime/RealtimeSession.ts
 var RealtimeSession = class {
   /**
@@ -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
@@ -4090,7 +4897,7 @@ var RealtimeSessionService = class _RealtimeSessionService {
       return void 0;
     }
     return new RealtimeSessionConnection({
-      provider: "trtc",
+      provider: "trtc" /* trtc */,
       roomID,
       sdkAppID,
       userID,
@@ -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: [
+            options.targetSize?.width ?? options.videoFormat.width,
+            options.targetSize?.height ?? options.videoFormat.height
+          ]
+        }
+      },
       user_id: options.userID,
-      uid: options.taskID
+      uid: options.taskID,
+      ...options.context.referenceVideo && { session_uid: options.taskID }
     });
   }
   /**
@@ -4452,20 +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;
       }
@@ -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");
       }
@@ -5019,6 +5837,7 @@ var StreamController = class {
      * 运行状态
      */
     __publicField(this, "state", makeInitialState());
+    __publicField(this, "roomListener");
     this.rtcManager = options.rtcManager;
     this.roomController = options.roomController ?? new RoomController({ rtcManager: options.rtcManager });
     this.encodingController = options.encodingController ?? new EncodingController({ rtcManager: options.rtcManager });
@@ -5027,13 +5846,19 @@ var StreamController = class {
     this.remoteStreamListener = options.remoteStreamListener ?? (() => {
     });
     this.generationTimeoutMs = options.generationTimeoutMs ?? 3e4;
+    this.roomController.setListener({
+      onRoomMessage: (sender, message) => {
+        this.handleNetworkVideoCompletion(sender, message);
+        this.roomListener?.onRoomMessage(sender, message);
+      }
+    });
     this.rtcManager.setEventListener({
       onTokenWillExpire: options.onCredentialsRequired,
       onTokenExpired: options.onCredentialsRequired,
       onRoomRejoining: () => this.handleRoomRejoining(),
       onError: (error) => this.errorListener(error),
       onNetworkStatistics: (statistics) => {
-        if (this.state.localVideoPublished) {
+        if (this.state.roomID) {
           this.networkStatisticsListener?.(statistics);
         }
       },
@@ -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: ${connection.botID ?? "(\u672A\u8BBE\u7F6E)"}`
     );
-    await beforePublish?.();
-    ensureActive();
-    await this.publishLocalStream(includeLocalAudio);
+    if (publishLocalMedia) {
+      await beforePublish?.();
+      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 options.onStartSent?.();
         if (this.state !== state2 || state2.generationTaskID !== taskID) return;
         for (const userID of state2.publishedRemoteUserIDs) {
           void this.handleRemoteVideoPublished(userID, true);
@@ -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,7 +6126,50 @@ var StreamController = class {
    * 设置房间业务消息监听器，传入空值时清除监听器。
    */
   setRoomListener(listener) {
-    this.roomController.setListener(listener);
+    this.roomListener = listener;
+  }
+  /**
+   * 生成状态已提交后登记完成通知，避免快速任务在启动返回前交付完成事件。
+   */
+  activateNetworkVideoCompletion(onFinish) {
+    const completion = this.state.networkVideoCompletion;
+    if (completion) {
+      completion.onFinish = onFinish;
+      this.deliverNetworkVideoCompletion();
+    }
+  }
+  /**
+   * 仅接受当前任务和目标机器人的完成消息；不因完成事件立即退房。
+   */
+  handleNetworkVideoCompletion(sender, message) {
+    const state2 = this.state;
+    const completion = state2.networkVideoCompletion;
+    if (!state2.roomID || !completion || completion.taskID !== state2.generationTaskID || message.event !== "video_stopped" || message.uid !== completion.taskID || !sender || state2.botID && sender !== state2.botID) {
+      return;
+    }
+    completion.finished = true;
+    this.deliverNetworkVideoCompletion();
+  }
+  /**
+   * 异步交付一次完成通知；执行前复核任务，隔离用户回调异常。
+   */
+  deliverNetworkVideoCompletion() {
+    const state2 = this.state;
+    const completion = state2.networkVideoCompletion;
+    if (!completion?.finished || !completion.onFinish || completion.scheduled) {
+      return;
+    }
+    completion.scheduled = true;
+    queueMicrotask(() => {
+      if (this.state !== state2 || state2.generationTaskID !== completion.taskID) {
+        return;
+      }
+      try {
+        void Promise.resolve(completion.onFinish?.()).catch(() => {
+        });
+      } catch {
+      }
+    });
   }
   /**
    * 配置当前房间；已有发布、订阅或生成任务时拒绝重新配置。
@@ -5527,6 +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) {
@@ -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;
   }
   /**
    * 开始等待用户授权系统媒体权限，返回授权决定时调用的记录函数。
@@ -6215,7 +7094,10 @@ var XmaxRealtimeConnectionManager = class {
         "Local video stream has no video format"
       );
     }
-    await streamController.setVideoEncoderConfig(videoFormat);
+    const publishLocalMedia = options.publishLocalMedia ?? true;
+    if (publishLocalMedia) {
+      await streamController.setVideoEncoderConfig(videoFormat);
+    }
     options.ensureCurrent();
     let completePublish;
     await streamController.connect(connection, options.includeLocalAudio, () => {
@@ -6225,8 +7107,9 @@ var XmaxRealtimeConnectionManager = class {
       await options.beforePublish?.();
       completeConnection();
       completePublish = this.dependencies.timing.startPublish();
-    });
+    }, publishLocalMedia);
     options.ensureCurrent();
+    completeConnection();
     completePublish?.();
     options.onPublished();
     sessionService.startHeartbeat(session.id, {
@@ -6275,7 +7158,7 @@ var XmaxRealtimeConnectionManager = class {
   async refreshCredentials() {
     if (this.credentialRefresh) return this.credentialRefresh;
     const current = this.activeSession;
-    if (!current?.connection || current.connection.provider === "trtc") return;
+    if (!current?.connection || current.connection.provider === "trtc" /* trtc */) return;
     const version = this.refreshVersion;
     const operation = (async () => {
       try {
@@ -6428,7 +7311,7 @@ var XmaxRealtimeConnectionManager = class {
       );
       return;
     }
-    if (next.provider !== "trtc" && (force || !previous || previous.provider === "trtc" || next.roomToken !== previous.roomToken)) {
+    if (next.provider !== "trtc" /* trtc */ && (force || !previous || previous.provider === "trtc" /* trtc */ || next.roomToken !== previous.roomToken)) {
       await this.dependencies.streamController.updateCredentials(next, this.credentialController?.signal);
       if (version !== this.refreshVersion || this.activeSession !== current) return;
     }
@@ -6526,7 +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();
@@ -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");
     /**
      * 启动计时与首帧通知
      */
@@ -6695,6 +7584,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     this.supportsInterpolation = dependencies?.supportsFrameInterpolation ?? (async (size) => await frameInterpolationAdapter(size) !== null);
     this.errorHandler = new RealtimeErrorHandler();
     const rtcManager = dependencies?.rtcManager ?? createRtcManager(options.provider, dependencies?.environment ?? "china" /* china */);
+    this.rtcManager = rtcManager;
     this.cameraController = dependencies?.cameraController ?? new CameraController({
       rtcManager,
       mediaService: this.mediaService,
@@ -6773,7 +7663,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    */
   async setFrameInterpolationEnabled(enabled) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const format = this.generationVideoFormat ?? this.cameraController.currentTrack?.videoFormat;
+      const format = this.generationVideoFormat ?? this.currentLocalTrack?.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);
       }
@@ -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 */
@@ -7035,6 +7925,63 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       }
     );
   }
+  /**
+   * 创建网络视频源并初始化接收端 RTC；预览是否加载成功不影响服务端读取视频。
+   */
+  async createNetworkVideoStream(options) {
+    return this.coordinator.run("media" /* media */, void 0, async (token) => {
+      this.ensureNoLocalSource();
+      const stream = this.networkVideoController.create(options, this.mediaService);
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      await this.rtcManager.initialize();
+      token.ensureCurrent();
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 创建文件音视频源并准备外部轨道；准备失败时统一释放本次媒体和 RTC 资源。
+   */
+  async createLocalVideoStream(options) {
+    return this.coordinator.run("media" /* media */, void 0, async (token) => {
+      this.ensureNoLocalSource();
+      if (!this.rtcManager.setExternalMediaTracks) {
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "The RTC provider does not support local video streams");
+      }
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      const stream = await this.localVideoController.create(options, this.mediaService, token.signal);
+      token.ensureCurrent();
+      await this.rtcManager.initialize();
+      token.ensureCurrent();
+      await this.rtcManager.setExternalMediaTracks({
+        videoTrack: stream.videoTrack.mediaStreamTrack,
+        audioTrack: this.localVideoController.audioTrack
+      });
+      token.ensureCurrent();
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /**
+   * 当前 Manager 拥有的媒体源轨道。
+   */
+  get currentLocalTrack() {
+    return this.localVideoController.currentTrack ?? this.networkVideoController.currentTrack ?? this.cameraController.currentTrack;
+  }
+  /**
+   * 创建前拒绝覆盖活动源，避免旧预览或连接资源被静默遗留。
+   */
+  ensureNoLocalSource() {
+    if (this.currentLocalTrack || this.localVideoController.isActive) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current local stream before creating another one");
+    }
+  }
   /**
    * 移除媒体权限弹窗观察；授权决定已记录或不再需要观察时调用。
    */
@@ -7046,14 +7993,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 应用完整的上行视频格式，成功后更新本地轨道元数据，不改变生成格式或生命周期。
    * 复用配置操作准入，避免与建连、切换摄像头或其他配置更新并发。
    *
-   * @throws 无本地相机流、参数无效、操作冲突或底层编码更新失败时抛错。
+   * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
   async updateVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const track = this.cameraController.currentTrack;
+      const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
       const previousFormat = track?.videoFormat;
       if (!track || !previousFormat) {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera stream is not started");
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera or file video stream is not started");
       }
       videoFormat.validate();
       await this.streamController.setVideoEncoderConfig(videoFormat);
@@ -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 = options.model?.trim();
+    if (!model) {
+      invalid("Model must not be empty");
+    }
+    const prompt = options.prompt.trim();
+    if (!prompt || [...prompt].length > 1024) {
+      invalid("Prompt must contain 1\u20131024 characters");
+    }
+    validateURL(options.videoPath);
+    if (options.referencePath !== void 0) {
+      validateURL(options.referencePath);
+    }
+    if (!Object.values(NonRealtimeQuality).includes(options.quality)) {
+      invalid("Quality must be sd or hd");
+    }
+    if (options.fps !== void 0 && !SUPPORTED_FPS.has(options.fps)) {
+      invalid("Unsupported processing frame rate");
+    }
+    const payload = await this.api.post("/offline-task", {
+      model,
+      prompt,
+      refVideoPath: options.videoPath.trim(),
+      ...options.referencePath === void 0 ? {} : { refImagePath: options.referencePath.trim() },
+      quality: options.quality,
+      ...options.fps === void 0 ? {} : { fps: options.fps }
+    });
+    return parseTask(payload);
+  }
+  /**
+   * 查询任务，校验返回 ID；signal 只取消本次 HTTP 查询，不取消服务端任务。
+   */
+  async getTask(taskUid, signal) {
+    const uid = validateTaskUid(taskUid);
+    const task = parseTask(await this.api.get(`/offline-task/${encodeURIComponent(uid)}`, { signal }));
+    if (task.uid !== uid) {
+      malformed("Task UID does not match the request");
+    }
+    return task;
+  }
+  /**
+   * 查询最多 100 个 ID，按首次出现顺序去重；任一任务不可用时整体失败。
+   */
+  async getTasks(taskUids) {
+    if (taskUids.length < 1 || taskUids.length > 100) {
+      invalid("Provide 1\u2013100 task UIDs");
+    }
+    const uids = [...new Set(taskUids.map(validateTaskUid))];
+    const payload = record(await this.api.post("/offline-task/batch-query", { taskUids: uids }));
+    const tasks = parseList(payload.list);
+    if (tasks.length !== uids.length || tasks.some((task, index) => task.uid !== uids[index])) {
+      malformed("Batch response does not match the requested task UIDs");
+    }
+    return tasks;
+  }
+  /**
+   * 分页查询任务，不隐式加载其他页。
+   */
+  async listTasks(options = {}) {
+    const pageNumber = options.pageNumber ?? 1;
+    const pageSize = options.pageSize ?? 10;
+    if (!Number.isSafeInteger(pageNumber) || pageNumber < 1) {
+      invalid("Page number must be a positive integer");
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+      invalid("Page size must be between 1 and 100");
+    }
+    if (options.status !== void 0 && !Object.values(NonRealtimeTaskStatus).includes(options.status)) {
+      invalid("Invalid task status");
+    }
+    const query = new URLSearchParams({ pageNumber: String(pageNumber), pageSize: String(pageSize) });
+    if (options.status !== void 0) {
+      query.set("status", options.status);
+    }
+    const payload = record(await this.api.get(`/offline-task/page?${query}`));
+    return Object.freeze({
+      pageNumber: pageInteger(payload, "pageNumber", 1),
+      pageSize: pageInteger(payload, "pageSize", 1),
+      total: pageInteger(payload, "total", 0),
+      list: parseList(payload.list)
+    });
+  }
+};
+function validateTaskUid(value) {
+  const uid = value.trim();
+  if (!uid || uid === "." || uid === "..") {
+    invalid("Task UID must not be empty or a relative path segment");
+  }
+  return uid;
+}
+function validateURL(value) {
+  let url;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    return invalid("Resource must be an uploaded HTTP(S) URL");
+  }
+  if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) {
+    invalid("Resource must be an uploaded HTTP(S) URL");
+  }
+}
+function invalid(message) {
+  throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, message);
+}
+function malformed(message = "Invalid non-realtime response data") {
+  throw new XmaxError("API_ERROR" /* apiError */, message);
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    malformed();
+  }
+  return value;
+}
+function field(data, key, type) {
+  const value = data[key];
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== type || typeof value === "number" && (!Number.isFinite(value) || value < 0)) {
+    malformed(`Invalid field: ${key}`);
+  }
+  return value;
+}
+function pageInteger(data, key, minimum) {
+  const value = field(data, key, "number");
+  if (value === void 0 || !Number.isSafeInteger(value) || value < minimum) {
+    malformed(`Invalid field: ${key}`);
+  }
+  return value;
+}
+function parseList(value) {
+  if (!Array.isArray(value)) {
+    malformed("Missing task list");
+  }
+  return Object.freeze(value.map(parseTask));
+}
+function parseTask(value) {
+  const data = record(value);
+  const uid = field(data, "uid", "string");
+  const status = field(data, "status", "string");
+  const quality = field(data, "quality", "string");
+  if (!uid?.trim() || !Object.values(NonRealtimeTaskStatus).includes(status)) {
+    malformed("Missing task UID or invalid status");
+  }
+  if (quality !== void 0 && !Object.values(NonRealtimeQuality).includes(quality)) {
+    malformed("Invalid task quality");
+  }
+  return Object.freeze({
+    uid,
+    status,
+    quality,
+    userUid: field(data, "userUid", "string"),
+    prompt: field(data, "prompt", "string"),
+    videoPath: field(data, "refVideoPath", "string"),
+    referencePath: field(data, "refImagePath", "string"),
+    processorId: field(data, "processorId", "string"),
+    requestedFps: field(data, "requestedFps", "number"),
+    resolvedFps: field(data, "resolvedFps", "number"),
+    retryCount: field(data, "retryCount", "number"),
+    videoDurationSeconds: field(data, "videoDurationSeconds", "number"),
+    billableDurationSeconds: field(data, "billableDurationSeconds", "number"),
+    chargePoints: field(data, "chargePoints", "number"),
+    result: data.result == null ? void 0 : parseResult(data.result),
+    processStartTime: field(data, "processStartTime", "string"),
+    createTimestamp: field(data, "createTimestamp", "string"),
+    updateTimestamp: field(data, "updateTimestamp", "string")
+  });
+}
+function parseResult(value) {
+  const data = record(value);
+  return Object.freeze({
+    url: field(data, "result_url", "string"),
+    uploadError: field(data, "upload_error", "string"),
+    uploadStatus: field(data, "upload_status", "string"),
+    finalizeDurationMs: field(data, "finalize_duration_ms", "number"),
+    compressionLevel: field(data, "compression_level", "string"),
+    frameCount: field(data, "frame_count", "number"),
+    fps: field(data, "fps", "number"),
+    durationMs: field(data, "result_duration_ms", "number"),
+    fileSizeBytes: field(data, "file_size_bytes", "number"),
+    droppedFrameCount: field(data, "dropped_frame_count", "number"),
+    originalFileSizeBytes: field(data, "original_file_size_bytes", "number")
+  });
+}
+
+// src/Service/NonRealtime/NonRealtimeTaskError.ts
+var NonRealtimeTaskError = class extends XmaxError {
+  /**
+   * 使用 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, options?.signal);
+  }
+  /**
+   * 批量取得任务快照。
+   */
+  getTasks(taskUids) {
+    return this.tasks.getTasks(taskUids);
+  }
+  /**
+   * 分页取得任务列表。
+   */
+  listTasks(options) {
+    return this.tasks.listTasks(options);
+  }
+  /**
+   * 等待任务完成；查询串行执行，瞬时错误有限退避，取消与总超时覆盖请求及等待阶段。
+   */
+  async waitForCompletion(taskUid, options = {}) {
+    const uid = validateTaskUid(taskUid);
+    const interval = options.intervalMs ?? 2e3;
+    const retries = options.maxConsecutiveRetries ?? 3;
+    validateDelay(interval);
+    if (options.timeoutMs !== void 0) {
+      validateDelay(options.timeoutMs);
+    }
+    if (!Number.isSafeInteger(retries) || retries < 0) {
+      throw new XmaxError(
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        "Retry count must be a non-negative integer"
+      );
+    }
+    const controller = new AbortController();
+    let timedOut = false;
+    const abort = () => controller.abort();
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted) {
+      abort();
+    }
+    const timer = options.timeoutMs === void 0 ? void 0 : setTimeout(() => {
+      timedOut = true;
+      abort();
+    }, options.timeoutMs);
+    let failures = 0;
+    try {
+      for (; ; ) {
+        ensureActive(controller.signal);
+        let task;
+        try {
+          task = await this.tasks.getTask(uid, controller.signal);
+        } catch (error) {
+          ensureActive(controller.signal);
+          if (!isTransient(error) || failures >= retries) {
+            throw error;
+          }
+          failures++;
+          await delay(Math.min(interval * 2 ** (failures - 1), 3e4), controller.signal);
+          continue;
+        }
+        ensureActive(controller.signal);
+        failures = 0;
+        try {
+          void Promise.resolve(options.onTaskUpdated?.(task)).catch(() => {
+          });
+        } catch {
+        }
+        ensureActive(controller.signal);
+        if (task.status === "error" /* error */) {
+          throw new NonRealtimeTaskError(task, `Non-realtime task ${uid} failed`);
+        }
+        if (task.status === "completed" /* completed */) {
+          if (!isResultAvailable(task)) {
+            throw new NonRealtimeTaskError(
+              task,
+              `Non-realtime task ${uid} completed without a usable result`
+            );
+          }
+          return task;
+        }
+        await delay(interval, controller.signal);
+      }
+    } catch (error) {
+      if (timedOut) {
+        throw new XmaxError(
+          "TIMEOUT" /* timeout */,
+          `Waiting for task ${uid} timed out; the server task was not cancelled`
+        );
+      }
+      ensureActive(controller.signal);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", abort);
+    }
+  }
+};
+function validateDelay(value) {
+  if (!Number.isFinite(value) || value <= 0 || value > 2147483647) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Polling durations must be positive and within the timer range");
+  }
+}
+function ensureActive(signal) {
+  if (signal.aborted) {
+    throw new XmaxError(
+      "CANCELLED" /* cancelled */,
+      "Task wait was cancelled locally; the server task was not cancelled"
+    );
+  }
+}
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const finish = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      try {
+        ensureActive(signal);
+        resolve();
+      } catch (error) {
+        reject(error);
+      }
+    };
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+    if (signal.aborted) {
+      finish();
+    }
+  });
+}
+function isTransient(error) {
+  if (!(error instanceof XmaxError)) {
+    return false;
+  }
+  return error.code === "NETWORK_ERROR" /* networkError */ || error.code === "TIMEOUT" /* timeout */ || error.code === "API_ERROR" /* apiError */ && (error.httpStatus ?? 0) >= 500 && (error.apiCode === void 0 || error.apiCode === error.httpStatus);
+}
+function isResultAvailable(task) {
+  const result = task.result;
+  if (!result?.url?.trim() || result.uploadError?.trim() || result.uploadStatus !== void 0 && result.uploadStatus !== "success") {
+    return false;
+  }
+  try {
+    const url = new URL(result.url);
+    return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
+
 // src/Core/XmaxClient.ts
 var XmaxClient = class {
   /**
@@ -7429,6 +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 = init.provider ?? "trtc" /* trtc */;
+    const providers = supportedRtcProviders(init.model);
+    this.provider = init.provider ?? providers[0];
     if (!Object.values(RtcProvider).includes(this.provider)) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Unsupported RTC provider");
     }
-    this.model = init.model;
-    const targetFrameRate = init.frameInterpolation?.targetFrameRate ?? 60;
-    if (!Number.isFinite(targetFrameRate) || targetFrameRate < 1 || targetFrameRate > 60) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Interpolation targetFrameRate must be between 1 and 60");
+    if (!providers.includes(this.provider)) {
+      throw new XmaxError(
+        "INVALID_CONFIGURATION" /* invalidConfiguration */,
+        `Model ${init.model} does not support RTC provider ${this.provider}`
+      );
     }
-    this.isFrameInterpolationEnabled = init.frameInterpolation?.enabled ?? init.isFrameInterpolationEnabled ?? false;
-    this.frameInterpolation = Object.freeze({ enabled: this.isFrameInterpolationEnabled, targetFrameRate });
+    this.model = init.model;
+    this.isFrameInterpolationEnabled = init.isFrameInterpolationEnabled ?? false;
   }
 };
 
@@ -7501,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 = init.referencePath?.trim();
-    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();
@@ -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);
   }
   /** 帧按显示时间升序入队；同一时间的内容后到先出。 */
@@ -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();
     }
@@ -10097,6 +11482,9 @@ var XmaxVideoView = class {
     this.setFrameInterpolation(void 0);
     this.cancelFrameDisplayNotification();
     this.videoElement.srcObject = null;
+    if (this.videoElement.getAttribute("src")) {
+      this.setVideoURL(null);
+    }
   }
   /**
    * 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。
@@ -10324,25 +11712,31 @@ export {
   XmaxError,
   RealtimeVideoEncoderPreference,
   RealtimeVideoFormat,
+  RtcProvider,
   RealtimeModel,
+  modelDisplayName,
   defaultFrameRate,
   defaultCameraVideoFormat,
+  supportedRtcProviders,
   MediaService,
   StoredFile,
   StorageService,
   CameraPosition,
-  RtcProvider,
   RealtimeVideoTrack,
   RealtimeMediaStream,
+  RealtimeVideoSampleMethod,
+  RealtimeContext,
   RealtimeConnectionState,
   RealtimeReason,
   RealtimeState,
   XmaxConfiguration,
+  NonRealtimeQuality,
+  NonRealtimeTaskStatus,
+  NonRealtimeTaskError,
   XmaxClient,
   RealtimeConfiguration,
   VideoContentMode,
-  RealtimeContext,
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-FMAQXPTE.js.map
+//# sourceMappingURL=chunk-VMJXIVUF.js.map