@xmaxai/web-sdk 1.0.6 → 1.0.8

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

@@ -205,7 +205,7 @@ var XmaxError = class _XmaxError extends Error {
 };
 
 // src/Foundation/Runtime/RuntimeInfo.ts
-var XMAX_SDK_VERSION = "1.0.6";
+var XMAX_SDK_VERSION = "1.0.8";
 var _RuntimeInfo = class _RuntimeInfo {
   /**
    * 序列化为接口传输使用的 snake_case 字段。
@@ -601,6 +601,7 @@ var RealtimeModel = /* @__PURE__ */ ((RealtimeModel2) => {
   RealtimeModel2["x2_0"] = "x2.0";
   RealtimeModel2["x2_0_trtc"] = "x2.0-trtc";
   RealtimeModel2["x2_1_preview"] = "x2.1-preview";
+  RealtimeModel2["x2_1_preview_1014"] = "x2.1-preview-1014";
   return RealtimeModel2;
 })(RealtimeModel || {});
 function isKnownModel(model) {
@@ -615,10 +616,12 @@ function modelDefaults(model) {
 var MODEL_DISPLAY_NAMES = {
   ["x2.0" /* x2_0 */]: "X2.0",
   ["x2.0-trtc" /* x2_0_trtc */]: "X2.1-preview-trtc",
-  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora"
+  ["x2.1-preview" /* x2_1_preview */]: "X2.1-preview-agora",
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "X2.1-preview-1014"
 };
 var MODEL_BASE_URLS = {
-  ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1"
+  ["x2.1-preview" /* x2_1_preview */]: "https://cloud.xmax.22duck.cn/open/api/v1",
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: "https://dev.xmaxai.com/open/api/v1"
 };
 var RESOLUTION_BUCKETS = {
   ["x2.0" /* x2_0 */]: [],
@@ -629,12 +632,17 @@ var RESOLUTION_BUCKETS = {
   ["x2.1-preview" /* x2_1_preview */]: [
     { width: 1024, height: 1920 },
     { width: 1920, height: 1024 }
+  ],
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: [
+    { width: 1024, height: 1920 },
+    { width: 1920, height: 1024 }
   ]
 };
 var MAXIMUM_INPUT_PIXELS = {
   ["x2.0" /* x2_0 */]: 128e4,
   ["x2.0-trtc" /* x2_0_trtc */]: 21e5,
-  ["x2.1-preview" /* x2_1_preview */]: 21e5
+  ["x2.1-preview" /* x2_1_preview */]: 21e5,
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: 21e5
 };
 function modelDisplayName(model) {
   return isKnownModel(model) ? MODEL_DISPLAY_NAMES[model] : model;
@@ -666,7 +674,8 @@ function defaultCameraVideoFormat(model) {
 var MODEL_RTC_PROVIDERS = {
   ["x2.0" /* x2_0 */]: Object.freeze(["vertc" /* vertc */]),
   ["x2.0-trtc" /* x2_0_trtc */]: Object.freeze(["trtc" /* trtc */]),
-  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */])
+  ["x2.1-preview" /* x2_1_preview */]: Object.freeze(["agora" /* agora */]),
+  ["x2.1-preview-1014" /* x2_1_preview_1014 */]: Object.freeze(["agora" /* agora */])
 };
 function supportedRtcProviders(model) {
   return isKnownModel(model) ? MODEL_RTC_PROVIDERS[model] : CUSTOM_MODEL_RTC_PROVIDERS;
@@ -1353,15 +1362,178 @@ var AgoraVideoSender = class {
       }
       throw new XmaxError("RTC_ERROR" /* rtcError */, "Browser did not retain WebRTC video sender parameters");
     }
-    XmaxLogger.rtc.info(() => `Agora \u53D1\u9001\u53C2\u6570\u5B9E\u9A8C (Agora Sender Parameters)
-${JSON.stringify({
-      capture: { width: capture.width, height: capture.height, frameRate: capture.frameRate },
-      target: { width: config.width, height: config.height, frameRate: config.frameRate },
-      scaleResolutionDownBy: actual.scaleResolutionDownBy,
-      maxFramerate: actual.maxFramerate,
-      maxBitrateKbps: actual.maxBitrate / 1e3,
-      minimumBitrateApplied: false
-    }, null, 2)}`, 2 /* performance */);
+  }
+};
+
+// src/Foundation/Media/Camera/CameraRotation.ts
+function validateCameraRotation(rotation) {
+  if (![0, 90, 180, 270].includes(rotation)) {
+    throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation must be 0, 90, 180 or 270");
+  }
+}
+
+// src/Foundation/Media/Camera/CameraRotationProcessor.ts
+var CameraRotationProcessor = class {
+  constructor(options) {
+    __publicField(this, "options", options);
+    __publicField(this, "video", document.createElement("video"));
+    __publicField(this, "canvas", document.createElement("canvas"));
+    __publicField(this, "context");
+    __publicField(this, "stream");
+    __publicField(this, "source");
+    __publicField(this, "frameCallback");
+    __publicField(this, "timer");
+    __publicField(this, "cancelPending");
+    __publicField(this, "stopped", false);
+    __publicField(this, "version", 0);
+    __publicField(this, "sourceEnded", () => {
+      this.fail(new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera source ended during rotation"));
+    });
+    this.canvas.width = options.width;
+    this.canvas.height = options.height;
+    const context = this.canvas.getContext("2d", { alpha: false });
+    if (!context || typeof this.canvas.captureStream !== "function") {
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Canvas camera rotation is not supported by this browser");
+    }
+    this.context = context;
+    this.video.muted = true;
+    this.video.autoplay = true;
+    this.video.playsInline = true;
+  }
+  /** 等待第一帧实际绘制成功；换摄像头时复用输出轨，不重建 sender。 */
+  async setSource(source) {
+    if (this.stopped) throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation has stopped");
+    if (source.readyState === "ended") {
+      this.stop();
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "Camera rotation requires a live source");
+    }
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    const version = ++this.version;
+    this.source = source;
+    source.addEventListener("ended", this.sourceEnded);
+    this.video.srcObject = new MediaStream([source]);
+    try {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timeout);
+          this.cancelPending = void 0;
+          if (error) reject(error);
+          else resolve();
+        };
+        const timeout = setTimeout(() => finish(new XmaxError("TIMEOUT" /* timeout */, "Timed out waiting for a camera rotation frame")), 1e4);
+        this.cancelPending = () => finish(new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed"));
+        void this.video.play().then(() => {
+          if (settled || this.stopped || version !== this.version) return;
+          const firstFrame = () => {
+            if (settled || this.stopped || version !== this.version) return;
+            try {
+              if (!this.draw()) {
+                this.schedule(firstFrame);
+                return;
+              }
+              this.stream ?? (this.stream = this.canvas.captureStream(this.options.frameRate));
+              if (!this.stream.getVideoTracks()[0]) throw new Error("Canvas did not produce a video track");
+              this.requestFrame();
+              finish();
+              this.schedule(() => this.render(version));
+            } catch (error) {
+              finish(error);
+            }
+          };
+          this.schedule(firstFrame);
+        }, finish);
+      });
+      if (this.stopped || version !== this.version) {
+        throw new XmaxError("CANCELLED" /* cancelled */, "Camera rotation source changed");
+      }
+      return this.stream.getVideoTracks()[0];
+    } catch (error) {
+      if (version === this.version) this.stop();
+      throw XmaxError.from(error);
+    }
+  }
+  /** 换设备前解除旧原始轨监听，保留 Canvas 最后一帧及输出轨。 */
+  pauseSource() {
+    ++this.version;
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+  }
+  stop() {
+    if (this.stopped) return;
+    this.stopped = true;
+    ++this.version;
+    this.cancelPending?.();
+    this.cancelFrame();
+    this.source?.removeEventListener("ended", this.sourceEnded);
+    this.source = void 0;
+    this.video.pause();
+    this.video.srcObject = null;
+    this.stream?.getTracks().forEach((track) => track.stop());
+    this.stream = void 0;
+    this.canvas.width = this.canvas.height = 0;
+  }
+  draw() {
+    const { videoWidth: width, videoHeight: height } = this.video;
+    if (this.video.readyState < 2 || !width || !height) return false;
+    const { width: outWidth, height: outHeight, rotation } = this.options;
+    const quarterTurn = rotation === 90 || rotation === 270;
+    const targetWidth = quarterTurn ? outHeight : outWidth;
+    const targetHeight = quarterTurn ? outWidth : outHeight;
+    const scale = Math.max(targetWidth / width, targetHeight / height);
+    const cropWidth = targetWidth / scale, cropHeight = targetHeight / scale;
+    this.context.setTransform(1, 0, 0, 1, outWidth / 2, outHeight / 2);
+    this.context.rotate(rotation * Math.PI / 180);
+    this.context.drawImage(
+      this.video,
+      (width - cropWidth) / 2,
+      (height - cropHeight) / 2,
+      cropWidth,
+      cropHeight,
+      -targetWidth / 2,
+      -targetHeight / 2,
+      targetWidth,
+      targetHeight
+    );
+    return true;
+  }
+  render(version) {
+    if (this.stopped || version !== this.version) return;
+    try {
+      if (this.draw()) this.requestFrame();
+      this.schedule(() => this.render(version));
+    } catch (error) {
+      this.fail(XmaxError.from(error));
+    }
+  }
+  requestFrame() {
+    const track = this.stream?.getVideoTracks()[0];
+    track?.requestFrame?.();
+  }
+  schedule(callback) {
+    if (typeof this.video.requestVideoFrameCallback === "function") {
+      this.frameCallback = this.video.requestVideoFrameCallback(callback);
+    } else {
+      this.timer = setTimeout(callback, 1e3 / this.options.frameRate);
+    }
+  }
+  cancelFrame() {
+    if (this.frameCallback !== void 0) this.video.cancelVideoFrameCallback(this.frameCallback);
+    clearTimeout(this.timer);
+    this.frameCallback = void 0;
+    this.timer = void 0;
+  }
+  fail(error) {
+    this.stop();
+    this.options.onError(error);
   }
 };
 
@@ -1381,6 +1553,9 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     __publicField(this, "initialization");
     __publicField(this, "lifecycle", 0);
     __publicField(this, "camera");
+    __publicField(this, "cameraSource");
+    __publicField(this, "cameraRotation");
+    __publicField(this, "captureVersion", 0);
     __publicField(this, "microphone");
     __publicField(this, "externalVideo");
     __publicField(this, "externalAudio");
@@ -1474,8 +1649,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
     this.clearRoom();
     this.client = void 0;
     client?.removeAllListeners();
-    this.releaseCameraSender();
-    this.camera?.close();
+    this.releaseCameraCapture();
     this.microphone?.close();
     this.externalVideo?.close();
     this.externalAudio?.close();
@@ -1499,19 +1673,41 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    */
   async startCameraCapture(options) {
     const client = this.requireClient();
-    if (this.camera || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "A local video source is already active");
     }
+    const rotation = options.rotation ?? 0;
+    validateCameraRotation(rotation);
+    const version = ++this.captureVersion;
+    let source;
     try {
-      const captureSize = rtcOrientedVideoSize(options);
-      const camera = await this.sdk.createCameraVideoTrack({
+      const captureSize = rtcOrientedVideoSize(rotation === 90 || rotation === 270 ? { width: options.height, height: options.width } : options);
+      source = await this.sdk.createCameraVideoTrack({
         facingMode: options.position === "front" /* front */ ? "user" : "environment",
         encoderConfig: { width: captureSize.width, height: captureSize.height, frameRate: options.frameRate }
       });
-      if (this.client !== client) {
-        camera.close();
+      if (this.client !== client || version !== this.captureVersion) {
+        source.close();
         throw this.cancelled();
       }
+      this.cameraSource = source;
+      let camera = source;
+      if (rotation !== 0) {
+        const processor = new CameraRotationProcessor({
+          ...options,
+          rotation,
+          onError: (error) => this.listener?.onError?.(error)
+        });
+        this.cameraRotation = processor;
+        const output = await processor.setSource(source.getMediaStreamTrack());
+        if (this.client !== client || version !== this.captureVersion) throw this.cancelled();
+        camera = this.sdk.createCustomVideoTrack({
+          mediaStreamTrack: output,
+          width: options.width,
+          height: options.height,
+          frameRate: options.frameRate
+        });
+      }
       this.camera = camera;
       this.cameraTransceiverListener = () => {
         if (this.client === client && client.localTracks.includes(camera) && this.videoPublishRequested && !this.rejoinTask) {
@@ -1525,6 +1721,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       camera.on("transceiver-updated", this.cameraTransceiverListener);
       return camera.getMediaStreamTrack();
     } catch (error) {
+      if (version === this.captureVersion) this.releaseCameraCapture();
       throw this.mapError(error, "CAMERA_PERMISSION_DENIED" /* cameraPermissionDenied */);
     }
   }
@@ -1532,9 +1729,24 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 切换声网相机设备并返回切换后的原生轨道。
    */
   async switchCameraCapture(to) {
-    const camera = this.requireCamera();
-    await this.run(() => camera.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
-    if (this.camera !== camera) throw this.cancelled();
+    const source = this.requireCamera();
+    const camera = this.camera;
+    this.cameraRotation?.pauseSource();
+    try {
+      await this.run(() => source.setDevice({ facingMode: to === "front" /* front */ ? "user" : "environment" }));
+    } catch (error) {
+      if (this.camera === camera && this.cameraRotation) {
+        await this.cameraRotation.setSource(source.getMediaStreamTrack()).catch((restoreError) => {
+          this.listener?.onError?.(XmaxError.from(restoreError));
+        });
+      }
+      throw error;
+    }
+    if (this.camera !== camera || this.cameraSource !== source) throw this.cancelled();
+    if (this.cameraRotation) {
+      await this.cameraRotation.setSource(source.getMediaStreamTrack());
+      if (this.camera !== camera) throw this.cancelled();
+    }
     if (this.videoPublishRequested) await this.restoreCameraSender(camera);
     return camera.getMediaStreamTrack();
   }
@@ -1542,17 +1754,25 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 停止采集并释放摄像头。
    */
   async stopCameraCapture() {
+    this.releaseCameraCapture();
+  }
+  releaseCameraCapture() {
+    ++this.captureVersion;
     const camera = this.camera;
     this.releaseCameraSender();
     this.camera = void 0;
     camera?.close();
+    this.cameraRotation?.stop();
+    this.cameraRotation = void 0;
+    if (this.cameraSource !== camera) this.cameraSource?.close();
+    this.cameraSource = void 0;
   }
   /**
    * 将外部原生轨包装为 Agora 本地轨，不申请设备权限；失败时释放本次克隆。
    */
   async setExternalMediaTracks(tracks) {
     this.requireClient();
-    if (this.camera || this.microphone || this.externalVideo) {
+    if (this.camera || this.cameraSource || this.microphone || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Release the current local media before attaching external tracks");
     }
     if (tracks.videoTrack.kind !== "video" || tracks.videoTrack.readyState !== "live" || tracks.audioTrack && (tracks.audioTrack.kind !== "audio" || tracks.audioTrack.readyState !== "live")) {
@@ -1592,7 +1812,7 @@ var _AgoraRtcManager = class _AgoraRtcManager {
         };
         ensureActive2();
         if (this.videoPublishRequested) {
-          await AgoraVideoSender.apply(camera, { ...config, ...rtcOrientedVideoSize(config) }, ensureActive2);
+          await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
         }
         this.cameraSenderConfiguration = { ...config };
       }));
@@ -1630,9 +1850,12 @@ var _AgoraRtcManager = class _AgoraRtcManager {
       };
       ensureActive2();
       const config = this.cameraSenderConfiguration;
-      if (config) await AgoraVideoSender.apply(camera, { ...config, ...rtcOrientedVideoSize(config) }, ensureActive2);
+      if (config) await AgoraVideoSender.apply(camera, this.cameraEncodingConfiguration(config), ensureActive2);
     });
   }
+  cameraEncodingConfiguration(config) {
+    return this.cameraRotation ? config : { ...config, ...rtcOrientedVideoSize(config) };
+  }
   releaseCameraSender() {
     if (this.cameraTransceiverListener) this.camera?.off("transceiver-updated", this.cameraTransceiverListener);
     this.cameraTransceiverListener = void 0;
@@ -2069,8 +2292,8 @@ var _AgoraRtcManager = class _AgoraRtcManager {
    * 获取已启动的相机采集。
    */
   requireCamera() {
-    if (!this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
-    return this.camera;
+    if (!this.cameraSource || !this.camera) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera capture is not running");
+    return this.cameraSource;
   }
   /**
    * 获取当前可编码、发布的视频轨，不要求来源为摄像头。
@@ -2509,6 +2732,9 @@ var TrtcRtcManager = class {
    * @throws 引擎未初始化、已在采集、设备不可用或权限被拒绝时抛出错误。
    */
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.isCapturing || this.externalVideo) {
       throw new XmaxError(
@@ -3155,6 +3381,9 @@ var VeRtcManager = class {
     }
   }
   async startCameraCapture(options) {
+    if (options.rotation !== void 0 && options.rotation !== 0) {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Camera rotation currently requires Agora");
+    }
     const engine = this.requireEngine();
     if (this.camera || this.externalVideo) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local video is already prepared");
@@ -3991,6 +4220,7 @@ var _CameraController = class _CameraController {
    *
    * @param options.videoFormat 期望的输出尺寸、帧率和编码配置；尺寸按模型规则调整。
    * @param options.position 首次启动时使用的摄像头位置。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @param options.useMicrophone 是否申请麦克风权限并允许实时连接时启动音频采集。
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
    * @returns 包含本地相机视频轨道的媒体流。
@@ -4003,6 +4233,7 @@ var _CameraController = class _CameraController {
         "Stop the current local camera stream before creating another one"
       );
     }
+    validateCameraRotation(options.rotation ?? 0);
     const resolvedFormat = this.resolveVideoFormat(options.videoFormat);
     const track = new RealtimeVideoTrack({
       id: _CameraController.localVideoTrackID,
@@ -4025,7 +4256,8 @@ var _CameraController = class _CameraController {
         width: resolvedFormat.width,
         height: resolvedFormat.height,
         frameRate: resolvedFormat.fps,
-        position: options.position
+        position: options.position,
+        ...options.rotation !== void 0 ? { rotation: options.rotation } : {}
       });
       track.mediaStreamTrack = mediaTrack;
       this.previewStream = new MediaStream([mediaTrack]);
@@ -4610,6 +4842,46 @@ var LocalVideoController = class {
   }
 };
 
+// src/Media/Video/ExternalVideoController.ts
+var ExternalVideoController = class {
+  constructor(onError) {
+    __publicField(this, "onError", onError);
+    __publicField(this, "track");
+    __publicField(this, "onEnded", () => {
+      this.onError(new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended"));
+    });
+  }
+  get currentTrack() {
+    return this.track;
+  }
+  create(options, mediaService) {
+    if (this.track) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Close the current external video first");
+    const { videoTrack, videoFormat } = options;
+    if (!videoTrack || videoTrack.kind !== "video" || videoTrack.readyState !== "live" || typeof videoTrack.clone !== "function") {
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video requires a live video MediaStreamTrack");
+    }
+    videoFormat.validate();
+    const size = mediaService.resolveModelInputSize(videoFormat);
+    const format = videoFormat.resized(size.width, size.height);
+    const nativeTrack = videoTrack.clone();
+    if (nativeTrack.readyState !== "live") {
+      nativeTrack.stop();
+      throw new XmaxError("MEDIA_ERROR" /* mediaError */, "External video source ended during setup");
+    }
+    const track = new RealtimeVideoTrack({ id: "external-video", videoFormat: format });
+    track.mediaStreamTrack = nativeTrack;
+    nativeTrack.addEventListener("ended", this.onEnded);
+    this.track = track;
+    return new RealtimeMediaStream({ id: "stream0" /* local */, videoTrack: track });
+  }
+  stop() {
+    const nativeTrack = this.track?.mediaStreamTrack;
+    this.track = void 0;
+    nativeTrack?.removeEventListener("ended", this.onEnded);
+    nativeTrack?.stop();
+  }
+};
+
 // src/Service/Realtime/RealtimeContext.ts
 var RealtimeContext = class {
   /**
@@ -5237,6 +5509,7 @@ var RoomEvent = class _RoomEvent {
   static generationParameters(options) {
     return {
       model: "default",
+      face_replace: options.faceRestoration ?? false,
       size: [options.videoFormat.width, options.videoFormat.height],
       target_size: options.targetSize ? [
         Math.round(options.targetSize.width),
@@ -5607,12 +5880,19 @@ var RoomController = class {
   /**
    * 发送生成开始信令。
    *
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.mirror 是否由后端镜像输入画面，默认 false。
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.targetSize 服务端生成后的回传尺寸，缺省使用生成尺寸。
+   * @param options.context 本次生成条件。
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   startGeneration(options) {
     return this.send(
       RoomEvent.start({
         mirror: options.mirror ?? false,
+        faceRestoration: options.faceRestoration ?? false,
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
@@ -5624,11 +5904,17 @@ var RoomController = class {
   /**
    * 发送生成条件变更信令。
    *
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.taskID 当前生成任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.targetSize 服务端生成后的回传尺寸。
+   * @param options.context 本次生成条件。
    * @throws 房间未就绪或信令发送失败时抛出错误。
    */
   changeGenerationCondition(options) {
     return this.send(
       RoomEvent.changeCondition({
+        faceRestoration: options.faceRestoration ?? false,
         userID: this.requireUserID(),
         taskID: options.taskID,
         videoFormat: options.videoFormat,
@@ -6162,6 +6448,7 @@ var StreamController = class {
       const sending = this.roomController.startGeneration({
         taskID,
         mirror: options.mirror ?? false,
+        faceRestoration: options.faceRestoration ?? false,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
@@ -6222,6 +6509,7 @@ var StreamController = class {
     try {
       await this.roomController.changeGenerationCondition({
         taskID: options.taskID,
+        faceRestoration: options.faceRestoration ?? false,
         videoFormat: options.videoFormat,
         targetSize: options.targetSize,
         context: options.context
@@ -7406,6 +7694,16 @@ var XmaxRealtimeConnectionManager = class {
    * 创建会话、配置编码、进房并发布本地媒体，启动心跳后返回远端占位流。
    * 进房结束即记录连接耗时；可选 beforePublish 检查阻塞发布，计入连接耗时；
    * 发布本地流单独计时。
+   * @param options.localTrack 当前本地媒体轨道。
+   * @param options.remoteVideoFormat 原始生成及远端画面规格，缺省使用本地轨道规格。
+   * @param options.localVideoFormat 发布前实际应用的上行编码格式；与原始生成及远端格式分开。
+   * @param options.onVideoEncoderConfigured 上行编码配置成功后的回调。
+   * @param options.model 创建业务会话使用的模型名称。
+   * @param options.includeLocalAudio 是否发布本地音频。
+   * @param options.ensureCurrent 校验当前操作仍有效。
+   * @param options.onPublished 本地发布完成后的回调。
+   * @param options.beforePublish 发布前的可选异步检查。
+   * @param options.publishLocalMedia 是否发布本地媒体，默认 true；网络视频源传 false。
    * @throws 会话、进房、发布失败或操作租约已失效时抛出错误，由上层统一清理。
    */
   async connect(options) {
@@ -7734,6 +8032,15 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
   /**
    * 发送生成指令并等待确认、远端就绪和音频激活，成功后返回任务标识。
    * 条件上下文在生成确认后缓存；启动失败时尽力停止本次任务并保留原始错误。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.targetSize 服务端生成后的回传尺寸，缺省使用生成尺寸。
+   * @param options.context 生成条件，缺省复用最近缓存的上下文。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
+   * @param options.mirror 是否由后端水平翻转输入，默认 false；仅用于 start 信令。
+   * @param options.signal 取消本次生成启动的信号。
+   * @param options.ensureCurrent 校验当前操作仍有效。
+   * @param options.waitUntilRemoteReady 等待远端生成流就绪。
+   * @param options.onStartSent start 信令发送成功后的可选异步回调。
    */
   async start(options) {
     const context = this.validateContext(options.context);
@@ -7747,6 +8054,7 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
         context,
         ...options.targetSize && { targetSize: options.targetSize },
         mirror: options.mirror ?? false,
+        faceRestoration: options.faceRestoration ?? false,
         ...options.onStartSent && { onStartSent: options.onStartSent }
       });
       await this.awaitConfirmation(confirmation, options.signal);
@@ -7764,6 +8072,11 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
   }
   /**
    * 更新活动任务的生成条件；信令发送成功后才覆盖缓存，无任务或上下文时抛错。
+   * @param taskID 当前活动任务标识。
+   * @param options.videoFormat 模型生成使用的视频规格。
+   * @param options.targetSize 服务端生成后的回传尺寸。
+   * @param options.context 生成条件，缺省复用最近缓存的上下文。
+   * @param options.faceRestoration 是否回贴原始人脸，默认 false。
    */
   async update(taskID, options) {
     const context = options.context ?? this.currentContext;
@@ -7774,6 +8087,7 @@ var XmaxRealtimeGenerationManager = class _XmaxRealtimeGenerationManager {
       taskID,
       videoFormat: options.videoFormat,
       context,
+      faceRestoration: options.faceRestoration ?? false,
       ...options.targetSize && { targetSize: options.targetSize }
     });
     if (this.activeTaskID !== taskID) throw RealtimeCoordinator.cancelledError();
@@ -7885,6 +8199,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     __publicField(this, "localVideoController", new LocalVideoController((error) => {
       void this.coordinator.terminateWithError(error, 0 /* connection */);
     }));
+    __publicField(this, "externalVideoController", new ExternalVideoController((error) => {
+      void this.coordinator.terminateWithError(error, 1 /* all */);
+    }));
     __publicField(this, "rtcManager");
     /**
      * 启动计时与首帧通知
@@ -7979,7 +8296,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           throw new XmaxError("CANCELLED" /* cancelled */, "Adaptive video format update was cancelled");
         }
         await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-          const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+          const track = this.currentUplinkTrack;
           const state2 = track && this.qualityStates.get(track);
           if (!track || !state2) throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Adaptive video baseline is unavailable");
           const format = qualityVideoFormat(state2.baseline, change.to);
@@ -8291,7 +8608,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    *
    * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
    *
+   * @param options.videoFormat 旋转后的目标规格，尺寸按模型规则解析。
+   * @param options.position 前置或后置摄像头。
+   * @param options.useMicrophone 是否采集并发布麦克风音频。
    * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待。
+   * @param options.rotation 输入帧顺时针旋转角度，默认 0；videoFormat 为旋转后的规格，目前仅 Agora 支持非零角度。
    * @returns 包含本地相机视频轨道的媒体流。
    * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
    */
@@ -8339,6 +8660,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
   /**
    * 创建网络视频源并初始化接收端 RTC；预览是否加载成功不影响服务端读取视频。
+   * @param options.url 服务端可直接访问的 HTTP/HTTPS 视频地址。
+   * @param options.videoFormat 模型输入及生成画面规格，不是上行编码参数。
+   * @param options.sampleMethod 服务端采样方式，默认 time。
+   * @param options.onFinish 服务端完成当前任务后的回调，不代表尾帧已播放完。
    */
   async createNetworkVideoStream(options) {
     return this.coordinator.run("media" /* media */, void 0, async (token) => {
@@ -8356,6 +8681,10 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
   /**
    * 创建文件音视频源并准备外部轨道；准备失败时统一释放本次媒体和 RTC 资源。
+   * @param options.file 包含可解码视频的本地 File 或 Blob。
+   * @param options.videoFormat 期望的视频规格；尺寸按宽高比匹配模型档位。
+   * @param options.loop 是否循环播放，默认 true。
+   * @param options.includeAudio 是否发送文件音频，默认 true。
    */
   async createLocalVideoStream(options) {
     return this.coordinator.run("media" /* media */, void 0, async (token) => {
@@ -8381,10 +8710,36 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     });
   }
   /**
-   * 当前 Manager 拥有的媒体源轨道。
+   * 接入外部视频轨；不创建采集设备或预览，所有异步失败统一释放 SDK 副本。
+   * @param options.videoTrack 用户自行采集或处理的 live 视频轨，原始轨道归调用方所有。
+   * @param options.videoFormat 期望的上传及生成规格，须符合模型规则；不代表修改输入像素。
    */
+  async createExternalVideoStream(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 external video streams");
+      }
+      const stream = this.externalVideoController.create(options, this.mediaService);
+      token.setFailureScope(1 /* all */);
+      this.launchTimer.start();
+      this.clearVideoStatistics();
+      await this.rtcManager.initialize();
+      token.ensureCurrent();
+      await this.rtcManager.setExternalMediaTracks({ videoTrack: stream.videoTrack.mediaStreamTrack });
+      token.ensureCurrent();
+      this.generationVideoFormat = stream.videoTrack?.videoFormat;
+      await this.coordinator.commit(new RealtimeState({ connectionState: "Ready" /* ready */ }), token);
+      return stream;
+    });
+  }
+  /** 当前可发布的本地视频轨，不包含服务端直接读取的网络视频。 */
+  get currentUplinkTrack() {
+    return this.externalVideoController.currentTrack ?? this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+  }
+  /** 当前 Manager 拥有的媒体源轨道。 */
   get currentLocalTrack() {
-    return this.localVideoController.currentTrack ?? this.networkVideoController.currentTrack ?? this.cameraController.currentTrack;
+    return this.currentUplinkTrack ?? this.networkVideoController.currentTrack;
   }
   /**
    * 创建前拒绝覆盖活动源，避免旧预览或连接资源被静默遗留。
@@ -8405,14 +8760,14 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 应用完整的上行视频格式，成功后更新本地轨道元数据，不改变生成格式或生命周期。
    * 复用配置操作准入，避免与建连、切换摄像头或其他配置更新并发。
    *
-   * @throws 无本地相机或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
+   * @throws 无本地相机、外部或文件视频流、参数无效、操作冲突或底层编码更新失败时抛错。
    */
   async updateUplinkVideoFormat(videoFormat) {
     await this.coordinator.run("configuration" /* configuration */, void 0, async (token) => {
-      const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+      const track = this.currentUplinkTrack;
       const previousFormat = track?.videoFormat;
       if (!track || !previousFormat) {
-        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera or file video stream is not started");
+        throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Local camera, external or file video stream is not started");
       }
       videoFormat.validate();
       this.qualityController?.stop();
@@ -8438,11 +8793,11 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   }
   /** 手动仅调帧接口，成功后的当前格式将成为新的自适应 L1 基准。 */
   async applyUplinkFrameRate(fps, token) {
-    const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+    const track = this.currentUplinkTrack;
     const previous = track?.videoFormat;
     const state2 = this.currentState.connectionState;
     if (!track || !previous || state2 !== "Connected" /* connected */ && state2 !== "Generating" /* generating */) {
-      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Frame rate updates require a connected local camera or file stream");
+      throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Frame rate updates require a connected local camera, external or file stream");
     }
     if (!Number.isFinite(fps) || fps <= 0) {
       throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "Video frame rate must be greater than zero");
@@ -8469,7 +8824,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       downlink.resetSamples();
       return;
     }
-    const track = this.localVideoController.currentTrack ?? this.cameraController.currentTrack;
+    const track = this.currentUplinkTrack;
     if (!track) {
       controller.stop();
     } else if (!controller.snapshot.active) {
@@ -8501,7 +8856,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 停止本地相机流并释放本地预览与 RTC 资源。
    */
   async stopLocalCameraStream() {
-    if (this.networkVideoController.currentTrack || this.localVideoController.isActive) {
+    if (this.networkVideoController.currentTrack || this.localVideoController.isActive || this.externalVideoController.currentTrack) {
       return;
     }
     await this.coordinator.run(
@@ -8534,6 +8889,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       "cameraSwitch" /* cameraSwitch */,
       void 0,
       async (token) => {
+        if (this.externalVideoController.currentTrack) {
+          throw new XmaxError("INVALID_CONFIGURATION" /* invalidConfiguration */, "External video capture is managed by the caller");
+        }
         this.qualityController?.stop();
         const stream = await this.cameraController.switchCamera();
         token.ensureCurrent();
@@ -8548,7 +8906,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
    * 返回的远端媒体流在生成开始后承载远端生成画面。
    *
-   * @param localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
+   * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
    * @returns 远端生成结果占位的媒体流。
    * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
    * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -8575,8 +8933,9 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
    * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
    * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
    *
-   * @param options.localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
+   * @param options.localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
    * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
+   * @param options.faceRestoration 是否启用原始人脸回贴，默认 false；正在生成时通过 change_condition 更新。
    * @returns 承载远端生成画面的媒体流。
    * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
    * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
@@ -8604,6 +8963,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         if (currentState.connectionState === "Generating" /* generating */) {
           await this.generationManager.update(currentState.taskID, {
             videoFormat,
+            faceRestoration: options.faceRestoration ?? false,
             targetSize: this.downlinkQualityController ? this.downlinkQualityState?.size : void 0,
             context: options.context
           });
@@ -8619,7 +8979,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
         if (currentState.connectionState !== "Connected" /* connected */) {
           await this.performConnect(options.localStream, token);
         }
-        return this.performStartGeneration(token, videoFormat, context);
+        return this.performStartGeneration(token, videoFormat, context, options.faceRestoration ?? false);
       }
     );
   }
@@ -8678,7 +9038,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
     if (token.signal.aborted) abortWarmup();
     try {
       let beforePublish;
-      if (!this.localVideoController.isActive && !this.networkVideoController.currentTrack && this.cameraController.isFrameValidationEnabled) {
+      if (localTrack === this.cameraController.currentTrack && this.cameraController.isFrameValidationEnabled) {
         const cameraReady = this.cameraController.waitForValidCameraFrame(warmupController.signal).then(() => {
           token.ensureCurrent();
         });
@@ -8700,7 +9060,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
           this.qualityHistory?.write("uplink", initialQuality.level);
         },
         model: this.options.model,
-        includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : !this.networkVideoController.currentTrack && this.cameraController.useMicrophone,
+        includeLocalAudio: this.localVideoController.isActive ? this.localVideoController.audioTrack !== void 0 : localTrack === this.cameraController.currentTrack && this.cameraController.useMicrophone,
         publishLocalMedia: !this.networkVideoController.currentTrack,
         ensureCurrent: () => token.ensureCurrent(),
         onPublished: () => {
@@ -8724,7 +9084,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
   /**
    * 编排插帧、首帧计时和生成状态，任务与确认由生成管理器负责。
    */
-  async performStartGeneration(token, videoFormat, context) {
+  async performStartGeneration(token, videoFormat, context, faceRestoration) {
     token.setFailureScope(0 /* connection */);
     const initialLevel = this.qualityHistory?.read("downlink") ?? 1;
     const targetSize = this.downlinkQualityController ? qualityVideoSize(videoFormat, initialLevel) : void 0;
@@ -8737,6 +9097,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
       videoFormat,
       targetSize,
       context,
+      faceRestoration,
       mirror: this.currentLocalTrack === this.cameraController.currentTrack && this.cameraController.currentTrack?.position === "front" /* front */,
       signal: token.signal,
       ensureCurrent: () => token.ensureCurrent(),
@@ -8801,12 +9162,12 @@ 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;
+      const hadExternalSource = this.networkVideoController.currentTrack !== void 0 || this.localVideoController.isActive || this.externalVideoController.currentTrack !== void 0;
       this.networkVideoController.stop();
       this.generationVideoFormat = void 0;
       this.disposePermissionWatch();
       try {
-        if (hadFileSource) {
+        if (hadExternalSource) {
           await this.rtcManager.destroy();
         } else {
           await this.cameraController.stopLocalCameraStream();
@@ -8817,6 +9178,7 @@ var XmaxRealtimeManager = class _XmaxRealtimeManager {
 \u2514\u2500 ${XmaxLogger.localized("\u539F\u56E0\uFF1A", "Reason: ")}${XmaxError.from(error).message}`
         );
       } finally {
+        this.externalVideoController.stop();
         if (this.localVideoController.isActive) {
           await this.localVideoController.stop();
         }
@@ -12467,4 +12829,4 @@ export {
   XmaxVideoView,
   XmaxRealtimeVideoView
 };
-//# sourceMappingURL=chunk-PLFWPS5A.js.map
+//# sourceMappingURL=chunk-JGDZ3RD3.js.map