@xmaxai/web-sdk 1.0.7 → 1.0.9

package/dist/chunk-V6TY7KAL.js

@@ -0,0 +1,8 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+export {
+  __publicField
+};
+//# sourceMappingURL=chunk-V6TY7KAL.js.map

package/dist/chunk-V6TY7KAL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.cjs

@@ -33,9 +33,10 @@
 
 
 
-var _chunkEKOYOFEScjs = require('./chunk-EKOYOFES.cjs');
 
 
+var _chunkKROY2O4Acjs = require('./chunk-KROY2O4A.cjs');
+require('./chunk-4DE2IREA.cjs');
 
 
 
@@ -69,5 +70,9 @@ var _chunkEKOYOFEScjs = require('./chunk-EKOYOFES.cjs');
 
 
 
-exports.CameraPosition = _chunkEKOYOFEScjs.CameraPosition; exports.MediaService = _chunkEKOYOFEScjs.MediaService; exports.NonRealtimeQuality = _chunkEKOYOFEScjs.NonRealtimeQuality; exports.NonRealtimeTaskError = _chunkEKOYOFEScjs.NonRealtimeTaskError; exports.NonRealtimeTaskStatus = _chunkEKOYOFEScjs.NonRealtimeTaskStatus; exports.RealtimeConfiguration = _chunkEKOYOFEScjs.RealtimeConfiguration; exports.RealtimeConnectionState = _chunkEKOYOFEScjs.RealtimeConnectionState; exports.RealtimeContext = _chunkEKOYOFEScjs.RealtimeContext; exports.RealtimeMediaStream = _chunkEKOYOFEScjs.RealtimeMediaStream; exports.RealtimeModel = _chunkEKOYOFEScjs.RealtimeModel; exports.RealtimeReason = _chunkEKOYOFEScjs.RealtimeReason; exports.RealtimeState = _chunkEKOYOFEScjs.RealtimeState; exports.RealtimeVideoEncoderPreference = _chunkEKOYOFEScjs.RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = _chunkEKOYOFEScjs.RealtimeVideoFormat; exports.RealtimeVideoSampleMethod = _chunkEKOYOFEScjs.RealtimeVideoSampleMethod; exports.RealtimeVideoTrack = _chunkEKOYOFEScjs.RealtimeVideoTrack; exports.RtcProvider = _chunkEKOYOFEScjs.RtcProvider; exports.StorageService = _chunkEKOYOFEScjs.StorageService; exports.StoredFile = _chunkEKOYOFEScjs.StoredFile; exports.VideoContentMode = _chunkEKOYOFEScjs.VideoContentMode; exports.XmaxClient = _chunkEKOYOFEScjs.XmaxClient; exports.XmaxConfiguration = _chunkEKOYOFEScjs.XmaxConfiguration; exports.XmaxEnvironment = _chunkEKOYOFEScjs.XmaxEnvironment; exports.XmaxError = _chunkEKOYOFEScjs.XmaxError; exports.XmaxErrorCode = _chunkEKOYOFEScjs.XmaxErrorCode; exports.XmaxLogger = _chunkEKOYOFEScjs.XmaxLogger; exports.XmaxLoggerOption = _chunkEKOYOFEScjs.XmaxLoggerOption; exports.XmaxRealtimeVideoView = _chunkEKOYOFEScjs.XmaxRealtimeVideoView; exports.XmaxVideoView = _chunkEKOYOFEScjs.XmaxVideoView; exports.apiBaseURL = _chunkEKOYOFEScjs.apiBaseURL; exports.defaultCameraVideoFormat = _chunkEKOYOFEScjs.defaultCameraVideoFormat; exports.defaultFrameRate = _chunkEKOYOFEScjs.defaultFrameRate; exports.modelDisplayName = _chunkEKOYOFEScjs.modelDisplayName; exports.supportedRtcProviders = _chunkEKOYOFEScjs.supportedRtcProviders;
+
+
+
+
+exports.CameraPosition = _chunkKROY2O4Acjs.CameraPosition; exports.MediaService = _chunkKROY2O4Acjs.MediaService; exports.NonRealtimeQuality = _chunkKROY2O4Acjs.NonRealtimeQuality; exports.NonRealtimeTaskError = _chunkKROY2O4Acjs.NonRealtimeTaskError; exports.NonRealtimeTaskStatus = _chunkKROY2O4Acjs.NonRealtimeTaskStatus; exports.RealtimeConfiguration = _chunkKROY2O4Acjs.RealtimeConfiguration; exports.RealtimeConnectionState = _chunkKROY2O4Acjs.RealtimeConnectionState; exports.RealtimeContext = _chunkKROY2O4Acjs.RealtimeContext; exports.RealtimeMediaStream = _chunkKROY2O4Acjs.RealtimeMediaStream; exports.RealtimeModel = _chunkKROY2O4Acjs.RealtimeModel; exports.RealtimeReason = _chunkKROY2O4Acjs.RealtimeReason; exports.RealtimeRecordingEventType = _chunkKROY2O4Acjs.RealtimeRecordingEventType; exports.RealtimeRecordingFinishReason = _chunkKROY2O4Acjs.RealtimeRecordingFinishReason; exports.RealtimeState = _chunkKROY2O4Acjs.RealtimeState; exports.RealtimeVideoEncoderPreference = _chunkKROY2O4Acjs.RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = _chunkKROY2O4Acjs.RealtimeVideoFormat; exports.RealtimeVideoSampleMethod = _chunkKROY2O4Acjs.RealtimeVideoSampleMethod; exports.RealtimeVideoTrack = _chunkKROY2O4Acjs.RealtimeVideoTrack; exports.RtcProvider = _chunkKROY2O4Acjs.RtcProvider; exports.StorageService = _chunkKROY2O4Acjs.StorageService; exports.StoredFile = _chunkKROY2O4Acjs.StoredFile; exports.VideoContentMode = _chunkKROY2O4Acjs.VideoContentMode; exports.XmaxClient = _chunkKROY2O4Acjs.XmaxClient; exports.XmaxConfiguration = _chunkKROY2O4Acjs.XmaxConfiguration; exports.XmaxEnvironment = _chunkKROY2O4Acjs.XmaxEnvironment; exports.XmaxError = _chunkKROY2O4Acjs.XmaxError; exports.XmaxErrorCode = _chunkKROY2O4Acjs.XmaxErrorCode; exports.XmaxLogger = _chunkKROY2O4Acjs.XmaxLogger; exports.XmaxLoggerOption = _chunkKROY2O4Acjs.XmaxLoggerOption; exports.XmaxRealtimeVideoView = _chunkKROY2O4Acjs.XmaxRealtimeVideoView; exports.XmaxVideoView = _chunkKROY2O4Acjs.XmaxVideoView; exports.apiBaseURL = _chunkKROY2O4Acjs.apiBaseURL; exports.defaultCameraVideoFormat = _chunkKROY2O4Acjs.defaultCameraVideoFormat; exports.defaultFrameRate = _chunkKROY2O4Acjs.defaultFrameRate; exports.modelDisplayName = _chunkKROY2O4Acjs.modelDisplayName; exports.supportedRtcProviders = _chunkKROY2O4Acjs.supportedRtcProviders;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-6u7tUB/source/packages/xmax-sdk/dist/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,unEAAC","file":"/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-6u7tUB/source/packages/xmax-sdk/dist/index.cjs"}
+{"version":3,"sources":["/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-Zggzaq/source/packages/xmax-sdk/dist/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,wDAA6B;AAC7B,gCAA6B;AAC7B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,myEAAC","file":"/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-Zggzaq/source/packages/xmax-sdk/dist/index.cjs"}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode, b as VideoRenderStatistics } from './VideoRenderStatistics-C7zqzfuS.cjs';
-export { c as RealtimeVideoEncoderPreference, d as RealtimeVideoFormatInit } from './VideoRenderStatistics-C7zqzfuS.cjs';
+import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode, T as TrajectoryEffectRendering, b as VideoRenderStatistics } from './TrajectoryEffectRendering-C7E2KJbV.cjs';
+export { c as RealtimeVideoEncoderPreference, d as RealtimeVideoFormatInit, e as TrajectoryID, f as TrajectoryPoint } from './TrajectoryEffectRendering-C7E2KJbV.cjs';
 
 /**
  * 实时媒体使用的 RTC 提供方；一个 Manager 生命周期内保持不变。
@@ -25,7 +25,10 @@ declare enum RtcProvider {
 declare enum RealtimeModel {
     x2_0 = "x2.0",
     x2_0_trtc = "x2.0-trtc",
-    x2_1_preview = "x2.1-preview"
+    x2_1_preview = "x2.1-preview",
+    x2_1_preview_1014 = "x2.1-preview-1014",
+    x2_1_1_preview_cn = "x2.1.1-preview-cn",
+    x2_1_1_preview_us = "x2.1.1-preview-us"
 }
 /** 内置模型或服务端新增的模型标识；自定义名称原样传给服务端。 */
 type RealtimeModelName = RealtimeModel | (string & {});
@@ -291,32 +294,12 @@ declare class RealtimeContext {
     constructor(init: RealtimeContextInit);
 }
 
-/**
- * 实时生成输入/输出的媒体流。
- */
-declare class RealtimeMediaStream {
-    /**
-     * 流标识与轨道
-     */
-    /**
-     * 媒体流标识。
-     */
-    readonly id: string;
-    /**
-     * 媒体流包含的视频轨道。
-     */
-    readonly videoTrack?: RealtimeVideoTrack;
-    /**
-     * 创建实时媒体流。
-     *
-     * @param init.id 媒体流标识。
-     * @param init.videoTrack 媒体流包含的视频轨道。
-     */
-    constructor(init: {
-        id: string;
-        videoTrack?: RealtimeVideoTrack;
-    });
-}
+/** 可通过生成信令传递的 JSON 数据。 */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** 合并到本次 start 或 change_condition 的 params；不缓存，不允许覆盖 SDK 字段。 */
+type RealtimeExtraParams = Record<string, JsonValue>;
 
 /**
  * SDK 向接入方暴露的统一错误码。
@@ -434,6 +417,84 @@ declare class XmaxError extends Error {
     static from(error: unknown): XmaxError;
 }
 
+/**
+ * 单次录制的最终事件类型。
+ */
+declare enum RealtimeRecordingEventType {
+    completed = "completed",
+    interrupted = "interrupted",
+    failed = "failed"
+}
+/**
+ * 已完成文件封装的录制结束原因。
+ */
+declare enum RealtimeRecordingFinishReason {
+    durationLimit = "durationLimit",
+    generationEnded = "generationEnded",
+    restarted = "restarted",
+    mediaInterrupted = "mediaInterrupted"
+}
+/**
+ * 已封装的录制文件；格式由 blob.type 指示，不保证为 MP4。
+ */
+interface RealtimeRecordingResult {
+    /**
+     * 可供保存、上传或预览的完整文件；成功裁去长帧等待时，时长短于实际录制时间。
+     */
+    readonly blob: Blob;
+    /**
+     * 录制期间是否接入过未静音的远端音频轨；不表示内容一定有声音。
+     */
+    readonly hasAudio: boolean;
+    /**
+     * 录制结束原因。
+     */
+    readonly reason: RealtimeRecordingFinishReason;
+}
+/**
+ * 录制终态；成功封装的提前结束返回 interrupted，无法提供有效文件返回 failed。
+ */
+type RealtimeRecordingEvent = {
+    type: RealtimeRecordingEventType.completed | RealtimeRecordingEventType.interrupted;
+    taskID: string;
+    result: RealtimeRecordingResult;
+} | {
+    type: RealtimeRecordingEventType.failed;
+    taskID: string;
+    error: XmaxError;
+};
+/**
+ * 每次录制交付一次最终事件，监听器异常不影响实时生成。
+ */
+type RealtimeRecordingListener = (event: RealtimeRecordingEvent) => void;
+
+/**
+ * 实时生成输入/输出的媒体流。
+ */
+declare class RealtimeMediaStream {
+    /**
+     * 流标识与轨道
+     */
+    /**
+     * 媒体流标识。
+     */
+    readonly id: string;
+    /**
+     * 媒体流包含的视频轨道。
+     */
+    readonly videoTrack?: RealtimeVideoTrack;
+    /**
+     * 创建实时媒体流。
+     *
+     * @param init.id 媒体流标识。
+     * @param init.videoTrack 媒体流包含的视频轨道。
+     */
+    constructor(init: {
+        id: string;
+        videoTrack?: RealtimeVideoTrack;
+    });
+}
+
 /**
  * 实时业务连接状态。
  */
@@ -638,6 +699,10 @@ type RemoteVideoStatisticsListener = (statistics: RemoteVideoStatistics | undefi
  * 定义 SDK 对接入方提供的实时媒体与生成控制能力。
  */
 interface XmaxRealtimeManaging {
+    /**
+     * 监听录制完成、中断或失败；传入 undefined 清除监听，不停止正在进行的录制。
+     */
+    setRecordingListener(listener?: RealtimeRecordingListener): void;
     /**
      * 实时能力配置。
      */
@@ -655,7 +720,14 @@ interface XmaxRealtimeManaging {
      */
     setFrameInterpolationEnabled(enabled: boolean): Promise<void>;
     /**
-     * 手动升/降一档下行输出尺寸，便于调试 change_target_size；仅支持正在生成的 Agora 会话。
+     * 手动升/降一档上行配置；仅支持正在生成的 Agora、TRTC 会话。
+     * Agora 调整分辨率、帧率和编码码率；TRTC 临时只调整帧率，保留尺寸和码率配置。
+     * 保留原始 L1 基准，不改变下行尺寸；自动调档仍保持开启。
+     * @param direction 升一档或降一档；到达 L1/L5 边界时不重复应用。
+     */
+    adjustUplinkQuality(direction: "upgrade" | "downgrade"): Promise<void>;
+    /**
+     * 手动升/降一档下行输出尺寸，便于调试 change_target_size；仅支持正在生成的 Agora、TRTC 会话。
      * 仅改变分辨率，成功发送后同步目标档位与插帧尺寸；自动调档仍保持开启。
      * 到达 L1/L5 边界时不重复发送；发送成功不代表服务端已生效。
      */
@@ -713,6 +785,11 @@ interface XmaxRealtimeManaging {
      *
      * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
      *
+     * @param options.videoFormat 旋转后的目标规格，尺寸按模型规则解析。
+     * @param options.position 前置或后置摄像头。
+     * @param options.useMicrophone 是否采集并发布麦克风音频。
+     * @param options.rotation 输入帧顺时针旋转角度，默认 0；非零角度目前仅支持 Agora，预览和上传均校正方向，镜像保持独立。
+     * @param options.enableFrameValidation 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待，不产生预热耗时。
      * @returns 包含本地相机视频轨道的媒体流。
      * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
      */
@@ -720,20 +797,14 @@ interface XmaxRealtimeManaging {
         videoFormat: RealtimeVideoFormat;
         position: CameraPosition;
         useMicrophone: boolean;
-        /**
-         * 输入帧顺时针旋转角度，默认 0；videoFormat 指旋转后的目标规格。
-         * 非零角度目前仅支持 Agora，预览和上传均校正方向，镜像保持独立。
-         */
         rotation?: CameraRotation;
-        /**
-         * 是否在发布前等待相机预热（固定 200ms），默认 true；false 跳过等待，不产生预热耗时。
-         */
         enableFrameValidation?: boolean;
     }): Promise<RealtimeMediaStream>;
     /**
      * 创建服务端直接读取的 HTTP/HTTPS 网络视频源，不采集或发布本地音视频。
      * 本地预览静音播放一次，独立于服务端进度；创建源不会开始生成。
      * 地址必须可由服务端直接访问，不转发浏览器 Cookie 或自定义鉴权头。
+     * @param options.url 服务端可直接访问的 HTTP/HTTPS 视频地址。
      * @param options.videoFormat 模型输入及生成画面规格，不是上行编码参数。
      * @param options.sampleMethod 服务端采样方式，默认 time。
      * @param options.onFinish 当前任务收到服务端完成消息且生成就绪后调用一次，不代表尾帧已播放完。
@@ -749,6 +820,7 @@ interface XmaxRealtimeManaging {
      * 从本地 File/Blob 创建文件视频源，支持 TRTC、Agora 和 VeRTC，不访问摄像头或麦克风。
      * 通过 Canvas 等比缩放补黑边，文件音频独立上行，本地预览始终静音。
      * 应从用户点击事件直接调用以解锁播放；创建后停在首帧，startGeneration 时开始播放。
+     * @param options.file 包含可解码视频的本地 File 或 Blob。
      * @param options.videoFormat 期望的视频规格；尺寸自动匹配最接近宽高比的模型档位，等距时优先横屏。
      * @param options.loop 是否循环播放文件音视频，默认 true。
      * @param options.includeAudio 是否发送文件音频，默认 true；无音轨文件输出静音，false 不创建音频轨。
@@ -760,16 +832,41 @@ interface XmaxRealtimeManaging {
         loop?: boolean;
         includeAudio?: boolean;
     }): Promise<RealtimeMediaStream>;
+    /**
+     * 从本地 File/Blob 创建图片视频流，支持 TRTC、Agora 和 VeRTC。
+     * 等比缩放并居中补黑边，持续发送同一静止画面，不上传文件、不采集摄像头或麦克风。
+     * 创建后可直接预览，仍需调用 startGeneration 开始生成；disconnect 保留图片源，close 释放全部资源。
+     * @param options.file 包含浏览器可解码图片的本地 File 或 Blob；动图仅取解码时的静止快照。
+     * @param options.videoFormat 期望的视频规格；尺寸自动匹配最接近宽高比的模型档位，等距时优先横屏。
+     * @throws 文件或格式无效、浏览器无法解码、Canvas 采集不可用或已有活动源时抛错。
+     */
+    createLocalImageStream(options: {
+        file: Blob;
+        videoFormat: RealtimeVideoFormat;
+    }): Promise<RealtimeMediaStream>;
+    /**
+     * 接收用户自行采集或处理的实时视频轨，仅视频，不采集或发送音频。
+     * 不要求绑定 SDK 预览；旋转、裁剪及本地预览由调用方负责，后端 mirror 固定 false。
+     * SDK 持有轨道副本：disconnect 保留输入，close 释放副本，不停止调用方原始轨道。
+     * 副本共享底层媒体源；调用方仍负责停止原始采集。设备源结束时 SDK 上报错误并关闭。
+     * @param options.videoTrack 用户自行采集或处理的 live 视频轨，原始轨道归调用方所有。
+     * @param options.videoFormat 期望的上传及生成规格，须符合模型规则；不代表修改输入像素。
+     * @throws 非 live 视频轨、不支持的格式、已有活动媒体源或 RTC 初始化失败时抛错。
+     */
+    createExternalVideoStream(options: {
+        videoTrack: MediaStreamTrack;
+        videoFormat: RealtimeVideoFormat;
+    }): Promise<RealtimeMediaStream>;
     /**
      * 更新当前本地流的上行视频格式，立即应用于 RTC 编码器，不重连或重启生成。
      * 传入完整格式；未指定的码率和编码偏好按 RealtimeVideoFormat 默认规则解析。
      * 成功后更新本地轨道的 videoFormat，后续重连继续使用该格式。
      * 模型生成及远端插帧仍使用创建本地流时的格式；此接口不改变生成尺寸。
      * 实际发送规格受设备、浏览器和网络影响，应通过统计回调确认。
-     * Agora 上行自适应以本次成功应用的完整格式作为新的 L1 基准，后续五档按比例调整尺寸和帧率。
+     * 上行自适应以本次成功应用的完整格式作为新的 L1 基准；Agora 按档位缩放尺寸和帧率，TRTC 临时仅调帧率。
      *
      * @param videoFormat 本次完整的上行尺寸、帧率和编码配置。
-     * @throws 无本地相机或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
+     * @throws 无本地相机、外部、图片或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
      */
     updateUplinkVideoFormat(videoFormat: RealtimeVideoFormat): Promise<void>;
     /**
@@ -799,7 +896,7 @@ interface XmaxRealtimeManaging {
      * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
      * 返回的远端媒体流在生成开始后承载远端生成画面。
      *
-     * @param localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
+     * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地图片、本地视频文件或网络视频源。
      * @returns 远端生成结果占位的媒体流。
      * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
      * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -817,18 +914,27 @@ interface XmaxRealtimeManaging {
     /**
      * 按需建立连接并开始生成。
      *
-     * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
+     * 尚未连接时先建立实时连接；已在生成时默认更新条件，restart 为 true 时重新开始生成。
      * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
      *
-     * @param options.localStream 由当前 Manager 创建的摄像头、本地文件或网络视频源。
+     * @param options.localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
      * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
+     * @param options.restart 是否保留 RTC 连接并创建新任务发送 start，默认 false；不预先发送 stop。
+     * @param options.faceRestoration 是否启用原始人脸回贴，默认 false；正在生成时通过 change_condition 更新。
+     * @param options.extraParams 合并到本次 start 或 change_condition 的 params；不缓存，自动恢复时不携带，不允许覆盖 SDK 字段。
+     * @param options.record 是否录制远端原始音视频约 20 秒，默认 false；仅 start 有效，条件更新时忽略，重启录制暂不支持。
      * @returns 承载远端生成画面的媒体流。
+     * @throws extraParams 包含非 JSON 数据、循环引用或 SDK 保留字段时，在连接或更新前抛出 invalidConfiguration。
      * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
      * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
      */
     startGeneration(options: {
         localStream: RealtimeMediaStream;
         context?: RealtimeContext;
+        restart?: boolean;
+        faceRestoration?: boolean;
+        extraParams?: RealtimeExtraParams;
+        record?: boolean;
     }): Promise<RealtimeMediaStream>;
 }
 
@@ -1517,6 +1623,12 @@ declare class XmaxVideoView {
      * DOM 挂载状态
      */
     private detached;
+    /**
+     * 轨迹交互配置与懒加载视图
+     */
+    private interactionEnabled;
+    private customTrajectoryRenderer?;
+    private trajectoryOverlay?;
     /**
      * 创建单轨视频视图。
      *
@@ -1524,7 +1636,24 @@ declare class XmaxVideoView {
      */
     constructor(options?: {
         videoContentMode?: VideoContentMode;
+        isInteractionEnabled?: boolean;
     });
+    /**
+     * 是否允许远端轨迹交互；本地轨道没有交互绑定，不受此开关影响。
+     */
+    get isInteractionEnabled(): boolean;
+    /**
+     * 关闭时立即取消当前手势，不影响视频播放。
+     */
+    set isInteractionEnabled(enabled: boolean);
+    /**
+     * 自定义轨迹视觉效果；undefined 表示使用 SDK 默认效果。
+     */
+    get trajectoryRenderer(): TrajectoryEffectRendering | undefined;
+    /**
+     * 替换效果前释放旧动画，采样及网络发送仍由 SDK 管理。
+     */
+    set trajectoryRenderer(renderer: TrajectoryEffectRendering | undefined);
     /**
      * 当前显示的视频轨道；切换时自动解绑旧轨道。
      */
@@ -1609,6 +1738,14 @@ declare class XmaxVideoView {
      * 视图未卸载时启动呈现统计，采样及媒体就绪检查由统计组件负责。
      */
     private startRenderStatistics;
+    /**
+     * 仅为具备交互能力的轨道创建覆盖层，普通视频和本地预览不分配 Canvas。
+     */
+    private attachTrajectory;
+    /**
+     * 换轨或卸载时移除全部交互资源；再次挂载时重新建立绑定。
+     */
+    private disposeTrajectory;
 }
 
 /**
@@ -1647,11 +1784,28 @@ declare class XmaxRealtimeVideoView {
         localTrack?: RealtimeVideoTrack;
         remoteTrack?: RealtimeVideoTrack;
         videoContentMode?: VideoContentMode;
+        isInteractionEnabled?: boolean;
     });
     /**
      * 当前显示的本地视频轨道。
      */
     get localTrack(): RealtimeVideoTrack | undefined;
+    /**
+     * 只控制远端视图的轨迹交互，本地预览始终不接管手势。
+     */
+    get isInteractionEnabled(): boolean;
+    /**
+     * 转交远端交互开关。
+     */
+    set isInteractionEnabled(enabled: boolean);
+    /**
+     * 远端视图的自定义轨迹效果。
+     */
+    get trajectoryRenderer(): TrajectoryEffectRendering | undefined;
+    /**
+     * undefined 恢复默认效果，不改变轨迹发送逻辑。
+     */
+    set trajectoryRenderer(renderer: TrajectoryEffectRendering | undefined);
     /**
      * 替换本地预览轨道；轨道未变化时保留当前绑定。
      */
@@ -1699,4 +1853,4 @@ declare class XmaxRealtimeVideoView {
     private showRemoteVideo;
 }
 
-export { CameraPosition, type CameraRotation, MediaService, type MediaServicing, type NetworkQualityLevel, type NetworkStatistics, type NetworkStatisticsListener, NonRealtimeQuality, type NonRealtimeResult, type NonRealtimeTask, NonRealtimeTaskError, type NonRealtimeTaskListOptions, type NonRealtimeTaskOptions, type NonRealtimeTaskPage, NonRealtimeTaskStatus, type NonRealtimeWaitOptions, RealtimeConfiguration, RealtimeConnectionState, RealtimeContext, type RealtimeContextInit, type RealtimeLaunchTiming, type RealtimeLaunchTimingListener, RealtimeMediaStream, RealtimeModel, type RealtimeModelName, RealtimeReason, type RealtimeReferenceVideo, RealtimeState, type RealtimeStateListener, RealtimeVideoFormat, RealtimeVideoSampleMethod, RealtimeVideoTrack, type RemoteVideoStatistics, type RemoteVideoStatisticsListener, RtcProvider, StorageService, type StorageServicing, type StorageUploadOptions, StoredFile, VideoContentMode, VideoRenderStatistics, type VideoStatistics, type VideoStatisticsListener, XmaxClient, XmaxConfiguration, type XmaxConfigurationInit, XmaxEnvironment, XmaxError, XmaxErrorCode, type XmaxErrorListener, XmaxLogger, XmaxLoggerOption, type XmaxNonRealtimeManaging, type XmaxRealtimeManaging, XmaxRealtimeVideoView, XmaxVideoView, apiBaseURL, defaultCameraVideoFormat, defaultFrameRate, modelDisplayName, supportedRtcProviders };
+export { CameraPosition, type CameraRotation, type JsonValue, MediaService, type MediaServicing, type NetworkQualityLevel, type NetworkStatistics, type NetworkStatisticsListener, NonRealtimeQuality, type NonRealtimeResult, type NonRealtimeTask, NonRealtimeTaskError, type NonRealtimeTaskListOptions, type NonRealtimeTaskOptions, type NonRealtimeTaskPage, NonRealtimeTaskStatus, type NonRealtimeWaitOptions, RealtimeConfiguration, RealtimeConnectionState, RealtimeContext, type RealtimeContextInit, type RealtimeExtraParams, type RealtimeLaunchTiming, type RealtimeLaunchTimingListener, RealtimeMediaStream, RealtimeModel, type RealtimeModelName, RealtimeReason, type RealtimeRecordingEvent, RealtimeRecordingEventType, RealtimeRecordingFinishReason, type RealtimeRecordingListener, type RealtimeRecordingResult, type RealtimeReferenceVideo, RealtimeState, type RealtimeStateListener, RealtimeVideoFormat, RealtimeVideoSampleMethod, RealtimeVideoTrack, type RemoteVideoStatistics, type RemoteVideoStatisticsListener, RtcProvider, StorageService, type StorageServicing, type StorageUploadOptions, StoredFile, TrajectoryEffectRendering, VideoContentMode, VideoRenderStatistics, type VideoStatistics, type VideoStatisticsListener, XmaxClient, XmaxConfiguration, type XmaxConfigurationInit, XmaxEnvironment, XmaxError, XmaxErrorCode, type XmaxErrorListener, XmaxLogger, XmaxLoggerOption, type XmaxNonRealtimeManaging, type XmaxRealtimeManaging, XmaxRealtimeVideoView, XmaxVideoView, apiBaseURL, defaultCameraVideoFormat, defaultFrameRate, modelDisplayName, supportedRtcProviders };