@xmaxai/web-sdk 1.0.8 → 1.0.10

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 _chunk24VPU65Tcjs = require('./chunk-24VPU65T.cjs');
 
 
+var _chunkUF2RD42Gcjs = require('./chunk-UF2RD42G.cjs');
+require('./chunk-4DE2IREA.cjs');
 
 
 
@@ -69,5 +70,9 @@ var _chunk24VPU65Tcjs = require('./chunk-24VPU65T.cjs');
 
 
 
-exports.CameraPosition = _chunk24VPU65Tcjs.CameraPosition; exports.MediaService = _chunk24VPU65Tcjs.MediaService; exports.NonRealtimeQuality = _chunk24VPU65Tcjs.NonRealtimeQuality; exports.NonRealtimeTaskError = _chunk24VPU65Tcjs.NonRealtimeTaskError; exports.NonRealtimeTaskStatus = _chunk24VPU65Tcjs.NonRealtimeTaskStatus; exports.RealtimeConfiguration = _chunk24VPU65Tcjs.RealtimeConfiguration; exports.RealtimeConnectionState = _chunk24VPU65Tcjs.RealtimeConnectionState; exports.RealtimeContext = _chunk24VPU65Tcjs.RealtimeContext; exports.RealtimeMediaStream = _chunk24VPU65Tcjs.RealtimeMediaStream; exports.RealtimeModel = _chunk24VPU65Tcjs.RealtimeModel; exports.RealtimeReason = _chunk24VPU65Tcjs.RealtimeReason; exports.RealtimeState = _chunk24VPU65Tcjs.RealtimeState; exports.RealtimeVideoEncoderPreference = _chunk24VPU65Tcjs.RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = _chunk24VPU65Tcjs.RealtimeVideoFormat; exports.RealtimeVideoSampleMethod = _chunk24VPU65Tcjs.RealtimeVideoSampleMethod; exports.RealtimeVideoTrack = _chunk24VPU65Tcjs.RealtimeVideoTrack; exports.RtcProvider = _chunk24VPU65Tcjs.RtcProvider; exports.StorageService = _chunk24VPU65Tcjs.StorageService; exports.StoredFile = _chunk24VPU65Tcjs.StoredFile; exports.VideoContentMode = _chunk24VPU65Tcjs.VideoContentMode; exports.XmaxClient = _chunk24VPU65Tcjs.XmaxClient; exports.XmaxConfiguration = _chunk24VPU65Tcjs.XmaxConfiguration; exports.XmaxEnvironment = _chunk24VPU65Tcjs.XmaxEnvironment; exports.XmaxError = _chunk24VPU65Tcjs.XmaxError; exports.XmaxErrorCode = _chunk24VPU65Tcjs.XmaxErrorCode; exports.XmaxLogger = _chunk24VPU65Tcjs.XmaxLogger; exports.XmaxLoggerOption = _chunk24VPU65Tcjs.XmaxLoggerOption; exports.XmaxRealtimeVideoView = _chunk24VPU65Tcjs.XmaxRealtimeVideoView; exports.XmaxVideoView = _chunk24VPU65Tcjs.XmaxVideoView; exports.apiBaseURL = _chunk24VPU65Tcjs.apiBaseURL; exports.defaultCameraVideoFormat = _chunk24VPU65Tcjs.defaultCameraVideoFormat; exports.defaultFrameRate = _chunk24VPU65Tcjs.defaultFrameRate; exports.modelDisplayName = _chunk24VPU65Tcjs.modelDisplayName; exports.supportedRtcProviders = _chunk24VPU65Tcjs.supportedRtcProviders;
+
+
+
+
+exports.CameraPosition = _chunkUF2RD42Gcjs.CameraPosition; exports.MediaService = _chunkUF2RD42Gcjs.MediaService; exports.NonRealtimeQuality = _chunkUF2RD42Gcjs.NonRealtimeQuality; exports.NonRealtimeTaskError = _chunkUF2RD42Gcjs.NonRealtimeTaskError; exports.NonRealtimeTaskStatus = _chunkUF2RD42Gcjs.NonRealtimeTaskStatus; exports.RealtimeConfiguration = _chunkUF2RD42Gcjs.RealtimeConfiguration; exports.RealtimeConnectionState = _chunkUF2RD42Gcjs.RealtimeConnectionState; exports.RealtimeContext = _chunkUF2RD42Gcjs.RealtimeContext; exports.RealtimeMediaStream = _chunkUF2RD42Gcjs.RealtimeMediaStream; exports.RealtimeModel = _chunkUF2RD42Gcjs.RealtimeModel; exports.RealtimeReason = _chunkUF2RD42Gcjs.RealtimeReason; exports.RealtimeRecordingEventType = _chunkUF2RD42Gcjs.RealtimeRecordingEventType; exports.RealtimeRecordingFinishReason = _chunkUF2RD42Gcjs.RealtimeRecordingFinishReason; exports.RealtimeState = _chunkUF2RD42Gcjs.RealtimeState; exports.RealtimeVideoEncoderPreference = _chunkUF2RD42Gcjs.RealtimeVideoEncoderPreference; exports.RealtimeVideoFormat = _chunkUF2RD42Gcjs.RealtimeVideoFormat; exports.RealtimeVideoSampleMethod = _chunkUF2RD42Gcjs.RealtimeVideoSampleMethod; exports.RealtimeVideoTrack = _chunkUF2RD42Gcjs.RealtimeVideoTrack; exports.RtcProvider = _chunkUF2RD42Gcjs.RtcProvider; exports.StorageService = _chunkUF2RD42Gcjs.StorageService; exports.StoredFile = _chunkUF2RD42Gcjs.StoredFile; exports.VideoContentMode = _chunkUF2RD42Gcjs.VideoContentMode; exports.XmaxClient = _chunkUF2RD42Gcjs.XmaxClient; exports.XmaxConfiguration = _chunkUF2RD42Gcjs.XmaxConfiguration; exports.XmaxEnvironment = _chunkUF2RD42Gcjs.XmaxEnvironment; exports.XmaxError = _chunkUF2RD42Gcjs.XmaxError; exports.XmaxErrorCode = _chunkUF2RD42Gcjs.XmaxErrorCode; exports.XmaxLogger = _chunkUF2RD42Gcjs.XmaxLogger; exports.XmaxLoggerOption = _chunkUF2RD42Gcjs.XmaxLoggerOption; exports.XmaxRealtimeVideoView = _chunkUF2RD42Gcjs.XmaxRealtimeVideoView; exports.XmaxVideoView = _chunkUF2RD42Gcjs.XmaxVideoView; exports.apiBaseURL = _chunkUF2RD42Gcjs.apiBaseURL; exports.defaultCameraVideoFormat = _chunkUF2RD42Gcjs.defaultCameraVideoFormat; exports.defaultFrameRate = _chunkUF2RD42Gcjs.defaultFrameRate; exports.modelDisplayName = _chunkUF2RD42Gcjs.modelDisplayName; exports.supportedRtcProviders = _chunkUF2RD42Gcjs.supportedRtcProviders;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-NxUj61/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-NxUj61/source/packages/xmax-sdk/dist/index.cjs"}
+{"version":3,"sources":["/private/var/folders/5j/p3g3j18x2w3byrl5wtnk94tc0000gn/T/xmax-web-release-ox16QE/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-ox16QE/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-BKKPO7Uk.cjs';
+export { c as RealtimeVideoEncoderPreference, d as RealtimeVideoFormatInit, e as TrajectoryID, f as TrajectoryPoint } from './TrajectoryEffectRendering-BKKPO7Uk.cjs';
 
 /**
  * 实时媒体使用的 RTC 提供方；一个 Manager 生命周期内保持不变。
@@ -23,10 +23,8 @@ declare enum RtcProvider {
  * SDK 当前支持的实时生成模型。
  */
 declare enum RealtimeModel {
-    x2_0 = "x2.0",
-    x2_0_trtc = "x2.0-trtc",
-    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 & {});
@@ -51,7 +49,7 @@ declare function defaultFrameRate(_model: RealtimeModelName): number;
 declare function defaultCameraVideoFormat(model: RealtimeModelName): RealtimeVideoFormat;
 /**
  * 查询 SDK 允许配置的 RTC 提供方，第一项为默认值。
- * 未知模型默认沿用 x2.1-preview 的 Agora，也允许显式选择其他已接入的 RTC；
+ * 未知模型默认沿用 x2.1.1-preview-cn 的 Agora，也允许显式选择其他已接入的 RTC；
  * 是否被该模型的服务端支持，由服务端决定。
  */
 declare function supportedRtcProviders(model: RealtimeModelName): readonly RtcProvider[];
@@ -191,7 +189,7 @@ declare class RealtimeConfiguration {
     /**
      * 创建实时业务配置。
      *
-     * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1-preview。
+     * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1.1-preview-cn。
      * @param init.provider RTC 提供方，默认按模型定义选择；必须受模型支持，创建后不可切换。
      * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧，默认 false。
      */
@@ -292,32 +290,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 向接入方暴露的统一错误码。
@@ -435,6 +413,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;
+    });
+}
+
 /**
  * 实时业务连接状态。
  */
@@ -460,7 +516,12 @@ declare enum RealtimeConnectionState {
      */
     connected = "Connected",
     /**
-     * 实时连接已建立且生成任务正在运行。
+     * 正在启动生成或等待 SDK 视频视图完成首帧及渲染预热。
+     * startGeneration 返回远端流后仍可能保持此状态，接入方需挂载视频视图。
+     */
+    starting = "Starting",
+    /**
+     * 生成任务正在运行，SDK 视频视图已完成渲染预热并开始展示画面。
      */
     generating = "Generating",
     /**
@@ -559,19 +620,27 @@ interface RealtimeLaunchTiming {
      */
     readonly permissionMs?: number;
     /**
-     * 开始创建会话到 RTC 进房配置与相机预热等待完成；不含发布本地流。
+     * 创建业务会话的耗时。
+     */
+    readonly sessionMs?: number;
+    /**
+     * RTC 适配器进房调用的耗时，不含房间消息配置、心跳启动、预热等待和本地流发布。
      */
-    readonly connectionMs?: number;
+    readonly rtcJoinMs?: number;
     /**
      * 发布本地流到 RTC 房间的耗时。
      */
     readonly publishMs?: number;
     /**
-     * 开始发送生成信令到 SDK 远端视图首次呈现视频帧。
+     * 开始发送生成信令到远端视频首帧提交合成器，不包含渲染预热。
      */
     readonly firstFrameMs?: number;
     /**
-     * 开始打开摄像头到 SDK 远端视图首次呈现视频帧的实际总耗时，并非各项之和。
+     * 远端首帧就绪到渲染预热结束的实际等待时间，不含渐入动画。
+     */
+    readonly renderWarmupMs?: number;
+    /**
+     * 开始打开摄像头到远端渲染预热结束、开始渐入的实际总耗时，并非各项之和。
      */
     readonly totalMs?: number;
 }
@@ -639,6 +708,10 @@ type RemoteVideoStatisticsListener = (statistics: RemoteVideoStatistics | undefi
  * 定义 SDK 对接入方提供的实时媒体与生成控制能力。
  */
 interface XmaxRealtimeManaging {
+    /**
+     * 监听录制完成、中断或失败；传入 undefined 清除监听，不停止正在进行的录制。
+     */
+    setRecordingListener(listener?: RealtimeRecordingListener): void;
     /**
      * 实时能力配置。
      */
@@ -656,7 +729,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 边界时不重复发送；发送成功不代表服务端已生效。
      */
@@ -761,6 +841,18 @@ 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。
@@ -780,10 +872,10 @@ interface XmaxRealtimeManaging {
      * 成功后更新本地轨道的 videoFormat，后续重连继续使用该格式。
      * 模型生成及远端插帧仍使用创建本地流时的格式；此接口不改变生成尺寸。
      * 实际发送规格受设备、浏览器和网络影响，应通过统计回调确认。
-     * Agora 上行自适应以本次成功应用的完整格式作为新的 L1 基准，后续五档按比例调整尺寸和帧率。
+     * 上行自适应以本次成功应用的完整格式作为新的 L1 基准；Agora 按档位缩放尺寸和帧率，TRTC 临时仅调帧率。
      *
      * @param videoFormat 本次完整的上行尺寸、帧率和编码配置。
-     * @throws 无本地相机、外部或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
+     * @throws 无本地相机、外部、图片或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
      */
     updateUplinkVideoFormat(videoFormat: RealtimeVideoFormat): Promise<void>;
     /**
@@ -813,7 +905,7 @@ interface XmaxRealtimeManaging {
      * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
      * 返回的远端媒体流在生成开始后承载远端生成画面。
      *
-     * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
+     * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地图片、本地视频文件或网络视频源。
      * @returns 远端生成结果占位的媒体流。
      * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
      * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -831,20 +923,28 @@ interface XmaxRealtimeManaging {
     /**
      * 按需建立连接并开始生成。
      *
-     * 尚未连接时先建立实时连接；已在生成时仅更新生成条件，不重启生成。
+     * 尚未连接时先建立实时连接；已在生成时默认更新条件，restart 为 true 时重新开始生成。
      * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
+     * 返回后请将远端流挂载到 SDK 视频视图；首帧及渲染预热完成后状态才进入 generating。
      *
      * @param options.localStream 由当前 Manager 创建的摄像头、外部视频轨、本地文件或网络视频源。
      * @param options.context 本次生成使用的条件上下文；缺省时复用缓存。
+     * @param options.restart 是否保留 RTC 连接并创建新任务发送 start，默认 false；不预先发送 stop。
      * @param options.faceRestoration 是否启用原始人脸回贴，默认 false；正在生成时通过 change_condition 更新。
-     * @returns 承载远端生成画面的媒体流。
+     * @param options.extraParams 合并到本次 start 或 change_condition 的 params；不缓存，自动恢复时不携带，不允许覆盖 SDK 字段。
+     * @param options.record 是否录制远端原始音视频约 20 秒，默认 false；仅 start 有效，条件更新时忽略，重启录制暂不支持。
+     * @returns 可挂载的远端媒体流，不等待渲染预热；展示就绪以 generating 状态为准。
+     * @throws extraParams 包含非 JSON 数据、循环引用或 SDK 保留字段时，在连接或更新前抛出 invalidConfiguration。
      * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
      * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
      */
     startGeneration(options: {
         localStream: RealtimeMediaStream;
         context?: RealtimeContext;
+        restart?: boolean;
         faceRestoration?: boolean;
+        extraParams?: RealtimeExtraParams;
+        record?: boolean;
     }): Promise<RealtimeMediaStream>;
 }
 
@@ -1204,7 +1304,7 @@ declare class XmaxClient {
     /**
      * 创建媒体处理与能力查询 Service。
      *
-     * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
+     * @param model 媒体输入规则使用的模型，默认为 `x2.1.1-preview-cn`。
      */
     createMediaService(model?: RealtimeModelName): MediaServicing;
     /**
@@ -1241,7 +1341,7 @@ declare class MediaService implements MediaServicing {
     /**
      * 创建媒体服务。
      *
-     * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
+     * @param model 媒体输入规则使用的模型，默认为 `x2.1.1-preview-cn`。
      */
     constructor(model?: RealtimeModelName);
     /**
@@ -1486,6 +1586,7 @@ interface RemoteFrameInterpolationOptions {
  *
  * 通过 `attach(to:)` 挂载到任意容器元素；设置 `track` 后自动渲染。
  * 轨道注册了渲染绑定时走绑定管线，否则按 `mediaStreamTrack` 直接渲染。
+ * SDK 远端轨道在首帧后预热 1000 ms，再用 300 ms 渐入；本地预览不延迟。
  */
 declare class XmaxVideoView {
     /**
@@ -1529,10 +1630,20 @@ declare class XmaxVideoView {
      * 呈现统计组件
      */
     private readonly statisticsController;
+    /**
+     * 远端画面预热与渐入组件
+     */
+    private readonly warmupController;
     /**
      * DOM 挂载状态
      */
     private detached;
+    /**
+     * 轨迹交互配置与懒加载视图
+     */
+    private interactionEnabled;
+    private customTrajectoryRenderer?;
+    private trajectoryOverlay?;
     /**
      * 创建单轨视频视图。
      *
@@ -1540,7 +1651,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);
     /**
      * 当前显示的视频轨道；切换时自动解绑旧轨道。
      */
@@ -1589,6 +1717,10 @@ declare class XmaxVideoView {
      * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
      */
     setMediaStream(stream: MediaStream | null): void;
+    /**
+     * 新生成任务重新等待首帧和预热，不替换正在播放的媒体流。 @internal
+     */
+    prepareForGeneration(): void;
     /**
      * 由远端绑定注入配置；本地预览不走此管线。 @internal
      */
@@ -1617,6 +1749,10 @@ declare class XmaxVideoView {
      * 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。
      */
     private cancelFrameDisplayNotification;
+    /**
+     * 仅远端渲染绑定启用预热，本地预览和普通媒体直接显示。
+     */
+    private prepareRenderWarmup;
     /**
      * 应用显示模式与镜像样式。
      */
@@ -1625,12 +1761,20 @@ declare class XmaxVideoView {
      * 视图未卸载时启动呈现统计，采样及媒体就绪检查由统计组件负责。
      */
     private startRenderStatistics;
+    /**
+     * 仅为具备交互能力的轨道创建覆盖层，普通视频和本地预览不分配 Canvas。
+     */
+    private attachTrajectory;
+    /**
+     * 换轨或卸载时移除全部交互资源；再次挂载时重新建立绑定。
+     */
+    private disposeTrajectory;
 }
 
 /**
  * 在本地预览和远端生成画面之间自动切换的视频容器（框架无关）。
  *
- * 设置远端轨道后，容器等待首帧实际提交显示再渐入远端画面；
+ * 设置 SDK 远端轨道后，等待首帧及渲染预热结束再渐入远端画面；
  * 远端轨道置空时立即恢复本地预览。
  */
 declare class XmaxRealtimeVideoView {
@@ -1663,18 +1807,35 @@ 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);
     /**
      * 替换本地预览轨道；轨道未变化时保留当前绑定。
      */
     set localTrack(track: RealtimeVideoTrack | undefined);
     /**
      * 当前显示的远端生成视频轨道。
-     * 设置新轨道后等待首帧提交显示再渐入；置空时立即恢复本地预览。
+     * SDK 远端轨道等待首帧及预热后渐入；置空时立即恢复本地预览。
      */
     get remoteTrack(): RealtimeVideoTrack | undefined;
     /**
@@ -1706,7 +1867,7 @@ declare class XmaxRealtimeVideoView {
      */
     detach(): void;
     /**
-     * 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。
+     * 更新远端轨道绑定；SDK 轨道共用单轨视图的预热，普通轨道等待首帧后渐入。
      */
     private updateRemoteTrack;
     /**
@@ -1715,4 +1876,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 };