@xmaxai/web-sdk 1.0.9 → 1.1.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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';
+import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode, T as TrajectoryEffectRendering, b as VideoRenderStatistics, c as TrajectoryPoint, d as TrajectoryID } from './TrajectoryEffectRendering-BdSJxHQw.cjs';
+export { e as RealtimeVideoEncoderPreference, f as RealtimeVideoFormatInit } from './TrajectoryEffectRendering-BdSJxHQw.cjs';
 
 /**
  * 实时媒体使用的 RTC 提供方；一个 Manager 生命周期内保持不变。
@@ -23,26 +23,40 @@ declare enum RtcProvider {
  * SDK 当前支持的实时生成模型。
  */
 declare enum RealtimeModel {
+    /**
+     * 使用 VeRTC 的 X2.0 实时生成模型。
+     */
     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"
+    /**
+     * 使用 Agora 的 X2.1 实时生成模型。
+     */
+    x2_1 = "x2.1"
 }
-/** 内置模型或服务端新增的模型标识；自定义名称原样传给服务端。 */
+/**
+ * 内置模型或服务端新增的模型标识；自定义名称原样传给服务端。
+ */
 type RealtimeModelName = RealtimeModel | (string & {});
 /**
  * 模型输入画面的像素尺寸。
  */
 interface ModelSize {
+    /**
+     * 视频宽度，单位为像素。
+     */
     width: number;
+    /**
+     * 视频高度，单位为像素。
+     */
     height: number;
 }
 /**
  * 获取模型的显示名称。
  */
 declare function modelDisplayName(model: RealtimeModelName): string;
+/**
+ * 模型支持的固定视频规格；空列表表示按像素预算解析，帧率为推荐默认值。
+ */
+declare function supportedVideoFormats(model: RealtimeModelName): RealtimeVideoFormat[];
 /**
  * 未指定视频规格时，各媒体来源使用的默认帧率。
  */
@@ -53,7 +67,7 @@ declare function defaultFrameRate(_model: RealtimeModelName): number;
 declare function defaultCameraVideoFormat(model: RealtimeModelName): RealtimeVideoFormat;
 /**
  * 查询 SDK 允许配置的 RTC 提供方，第一项为默认值。
- * 未知模型默认沿用 x2.1-preview 的 Agora，也允许显式选择其他已接入的 RTC；
+ * 未知模型默认使用 Agora，也允许显式选择其他已接入的 RTC；
  * 是否被该模型的服务端支持，由服务端决定。
  */
 declare function supportedRtcProviders(model: RealtimeModelName): readonly RtcProvider[];
@@ -63,15 +77,27 @@ declare function supportedRtcProviders(model: RealtimeModelName): readonly RtcPr
  */
 interface MediaServicing {
     /**
-     * 校验并保留原始尺寸；Web 插帧不降低回传分辨率。
+     * 当前媒体规则使用的模型。
+     */
+    readonly model: RealtimeModelName;
+    /**
+     * 解析原始媒体尺寸，不放大、限制像素面积并按 4 对齐；仅摄像头校验模型桶。
+     *
+     * @param sourceMediaSize 原始媒体尺寸。
+     * @param source 媒体来源，文件媒体和外部轨道接受任意比例。
+     * @returns 用于固定媒体基准和初始上行编码的尺寸。
+     */
+    resolveMediaSize(sourceMediaSize: ModelSize, source: "camera" | "image" | "video" | "external"): ModelSize;
+    /**
+     * 为处理后的媒体选择模型生成画布，不改变本地媒体规格。
      */
-    resolveFrameInterpolationSize(size: ModelSize): ModelSize;
+    resolveGenerationSize(resolvedMediaSize: ModelSize): ModelSize;
     /**
-     * 异步判断平台是否支持指定尺寸的插帧；不代表运行期性能保证。
+     * 根据固定媒体基准和下行尺寸上限计算 4 对齐回传尺寸。
      */
-    supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
+    resolveTargetSize(resolvedMediaSize: ModelSize, maximumSize: ModelSize): ModelSize;
     /**
-     * 按模型输入规则解析目标尺寸。
+     * 解析模型支持的采集规格或生成画布，不处理媒体像素。
      *
      * 分辨率桶非空时必须精确匹配；否则按像素面积上下限等比缩放并对齐到
      * 模型要求的像素倍数。
@@ -85,9 +111,6 @@ interface MediaServicing {
  * 上传完成后返回的已存储文件信息。
  */
 declare class StoredFile {
-    /**
-     * 存储结果
-     */
     /**
      * 文件的访问地址。
      */
@@ -102,10 +125,6 @@ declare class StoredFile {
     readonly etag?: string;
     /**
      * 创建已存储文件信息。
-     *
-     * @param init.url 文件访问地址。
-     * @param init.objectKey 对象键。
-     * @param init.etag 对象存储返回的 ETag。
      */
     constructor(init: {
         url: string;
@@ -179,87 +198,87 @@ interface StorageServicing {
  */
 declare class RealtimeConfiguration {
     /**
-     * 实时生成业务使用的模型。
+     * 实时生成使用的模型；未知名称原样透传到测试环境，媒体与 RTC 默认配置同 X2.1。
      */
     readonly model: RealtimeModelName;
     /**
-     * 实时连接使用的 RTC 提供方。
+     * 实时连接使用的 RTC 提供方，默认取模型支持列表的首项，创建后不可切换。
      */
     readonly provider: RtcProvider;
     /**
-     * 是否默认请求开启远端生成画面的插帧。
+     * 是否自动调整上下行档位，默认 true。关闭时从 L1 启动且不读写历史档位，仍支持手动调档。
      */
-    readonly isFrameInterpolationEnabled: boolean;
+    readonly isAdaptiveQualityEnabled: boolean;
     /**
-     * 创建实时业务配置。
-     *
-     * @param init.model 实时生成业务使用的模型；未知名称原样透传，默认配置同 x2.1-preview。
-     * @param init.provider RTC 提供方，默认按模型定义选择；必须受模型支持，创建后不可切换。
-     * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧，默认 false。
+     * 补全 RTC 和自动调档默认值，并校验模型名称与 RTC 提供方配置。
      */
     constructor(init: {
         model: RealtimeModelName;
         provider?: RtcProvider;
-        isFrameInterpolationEnabled?: boolean;
+        isAdaptiveQualityEnabled?: boolean;
     });
 }
 
-/** 输入帧顺时针旋转角度；与前置摄像头的水平镜像独立。 */
-type CameraRotation = 0 | 90 | 180 | 270;
-
 /**
- * RTC 网络质量等级：未知、极好、良好、一般、差、极差、断网。
+ * 输入帧顺时针旋转角度；与前置摄像头的水平镜像独立。
  */
-type NetworkQualityLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+type CameraRotation = 0 | 90 | 180 | 270;
+
 /**
- * 本端 RTC 连接的网络统计，不依赖远端生成流是否已经到达。
+ * 实时连接的网络质量等级。
  */
-interface NetworkStatistics {
-    readonly uplinkQuality?: NetworkQualityLevel;
+declare enum RealtimeNetworkQualityLevel {
     /**
-     * 所有下行连接的平均网络质量。
+     * 尚无有效的质量评估。
      */
-    readonly downlinkQuality?: NetworkQualityLevel;
+    unknown = "Unknown",
     /**
-     * 上行连接到 RTC 云端的往返延迟，单位 ms，不是单程延迟；Agora 未提供时为空。
+     * 网络质量极好。
      */
-    readonly uplinkRttMs?: number;
+    excellent = "Excellent",
     /**
-     * 所有下行连接到 RTC 云端的平均往返延迟，单位 ms；Agora 未提供时为空。
+     * 网络质量良好。
      */
-    readonly downlinkRttMs?: number;
-}
-/**
- * undefined 表示尚无采样或连接已清理。
- */
-type NetworkStatisticsListener = (statistics: NetworkStatistics | undefined) => void;
-
-/**
- * 服务端读取网络视频时使用的采样方式。
- */
-declare enum RealtimeVideoSampleMethod {
-    time = "time",
-    fps = "fps"
+    good = "Good",
+    /**
+     * 网络质量一般，可能影响实时播放。
+     */
+    poor = "Poor",
+    /**
+     * 网络质量差，影响实时播放。
+     */
+    bad = "Bad",
+    /**
+     * 网络质量极差，可能严重中断媒体传输。
+     */
+    veryBad = "VeryBad",
+    /**
+     * 网络连接已断开。
+     */
+    down = "Down"
 }
 /**
- * 服务端可直接访问的网络视频及采样配置。
+ * 本端 RTC 连接的网络统计，不依赖远端生成流是否已经到达。
  */
-interface RealtimeReferenceVideo {
+interface RealtimeNetworkQuality {
     /**
-     * HTTP 或 HTTPS 视频地址。
+     * 上行网络质量等级，沿用 RTC 厂商的评估结果。
      */
-    readonly path: string;
+    readonly uplink: RealtimeNetworkQualityLevel;
     /**
-     * 服务端采样方式。
+     * 所有下行连接的平均网络质量。
      */
-    readonly sampleMethod: RealtimeVideoSampleMethod;
+    readonly downlink: RealtimeNetworkQualityLevel;
 }
+/**
+ * undefined 表示尚无采样或连接已清理。
+ */
+type RealtimeNetworkQualityListener = (statistics: RealtimeNetworkQuality | undefined) => void;
 
+/**
+ * 实时生成指令和参考资源。
+ */
 interface RealtimeContextInit {
-    /**
-     * 服务端直接读取的网络视频。
-     */
-    referenceVideo?: RealtimeReferenceVideo;
     /**
      * 实时生成使用的文本条件。
      */
@@ -273,13 +292,6 @@ interface RealtimeContextInit {
  * 单次实时生成任务的文本和参考资源上下文。
  */
 declare class RealtimeContext {
-    /**
-     * 服务端直接读取的网络视频。
-     */
-    readonly referenceVideo?: RealtimeReferenceVideo;
-    /**
-     * 生成条件
-     */
     /**
      * 实时生成使用的文本条件。
      */
@@ -294,13 +306,143 @@ declare class RealtimeContext {
     constructor(init: RealtimeContextInit);
 }
 
-/** 可通过生成信令传递的 JSON 数据。 */
+/**
+ * 可通过生成信令传递的 JSON 数据。
+ */
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-/** 合并到本次 start 或 change_condition 的 params；不缓存，不允许覆盖 SDK 字段。 */
+/**
+ * 合并到本次 start 或 change_condition 的 params；不缓存，不允许覆盖 SDK 字段。
+ */
 type RealtimeExtraParams = Record<string, JsonValue>;
 
+/**
+ * 已复制的远端 PCM 音频包，格式为有符号、小端、交错排列的 16 位样本。
+ */
+interface RealtimeAudioFrame {
+    /**
+     * 音频字节；回调返回后仍可持有。
+     */
+    readonly data: Uint8Array;
+    /**
+     * 每个声道每秒的样本数。
+     */
+    readonly sampleRate: number;
+    /**
+     * 交错排列的声道数。
+     */
+    readonly channels: number;
+    /**
+     * 本包每个声道的样本数。
+     */
+    readonly samplesPerChannel: number;
+    /**
+     * 首个样本在接收端呈现时间轴上的时间，单位为微秒，不保证从零开始。
+     */
+    readonly presentationTimeStamp: number;
+    /**
+     * 按样本数和采样率计算的时长，单位为微秒。
+     */
+    readonly duration: number;
+}
+/**
+ * 原始远端解码视频帧，不包含镜像、裁剪或界面叠层。
+ */
+interface RealtimeVideoFrame {
+    /**
+     * 由接入方持有的只读帧；使用或异步编码完成后必须调用 close()。
+     */
+    readonly frame: VideoFrame;
+    /**
+     * 接收端呈现时间轴上的时间，单位为微秒，与音频使用相同时间基准。
+     */
+    readonly presentationTimeStamp: number;
+    /**
+     * 建议呈现时长，单位为微秒；无法确定时为空。
+     */
+    readonly duration?: number;
+}
+/**
+ * 一包远端媒体，不表示一对音视频帧；按同一个录制起点和时间戳进行同步。
+ */
+interface RealtimeMediaFrame {
+    /**
+     * 同一结果流绑定的音视频共享标识；换流或重连后更新。
+     */
+    readonly streamID: string;
+    /**
+     * 当前轨首次输出、格式/时钟变化或丢弃输出后为 true；SDK 不压缩时间轴。
+     */
+    readonly isDiscontinuous: boolean;
+    /**
+     * 音频包或视频帧。
+     */
+    readonly content: {
+        readonly type: "audio";
+        readonly frame: RealtimeAudioFrame;
+    } | {
+        readonly type: "video";
+        readonly frame: RealtimeVideoFrame;
+    };
+    /**
+     * 媒体时间戳，单位为微秒，与 content.frame.presentationTimeStamp 一致。
+     */
+    readonly presentationTimeStamp: number;
+    /**
+     * 包时长，单位为微秒；视频无法确定时为空。
+     */
+    readonly duration?: number;
+}
+/**
+ * 按交付顺序接收媒体，不保证跨音视频轨的时间戳顺序。
+ * 回调须保持轻量，异步处理请自行排队；视频帧所有权转移给接入方，音频可直接保留。
+ */
+type RealtimeMediaFrameListener = (frame: RealtimeMediaFrame) => void;
+
+/**
+ * 当前结果流的原始媒体轨，仅借用，不转移 RTC 轨道所有权。
+ */
+interface RemoteMediaTracks {
+    /**
+     * 生成任务的绑定标识，用于隔离同一 RTC 轨上的不同任务。
+     */
+    readonly bindingID: string;
+    /**
+     * 实际结果流的 RTC 用户。
+     */
+    readonly userID: string;
+    /**
+     * 订阅到的远端原始视频轨。
+     */
+    readonly videoTrack: MediaStreamTrack;
+    /**
+     * 播放音量处理前的远端音轨；音频尚未发布或没有音轨时为空。
+     */
+    readonly audioTrack?: MediaStreamTrack;
+}
+
+/**
+ * 实时生成输入/输出的媒体流。
+ */
+declare class RealtimeMediaStream {
+    /**
+     * 媒体流标识。
+     */
+    readonly id: string;
+    /**
+     * 媒体流包含的视频轨道。
+     */
+    readonly videoTrack?: RealtimeVideoTrack;
+    /**
+     * 创建实时媒体流。
+     */
+    constructor(init: {
+        id: string;
+        videoTrack?: RealtimeVideoTrack;
+    });
+}
+
 /**
  * SDK 向接入方暴露的统一错误码。
  */
@@ -337,10 +479,6 @@ declare enum XmaxErrorCode {
      * 本地媒体读取、解码、同步或帧处理发生错误。
      */
     mediaError = "MEDIA_ERROR",
-    /**
-     * 当前系统、设备或视频规格不支持远端视频插帧。
-     */
-    frameInterpolationUnsupported = "FRAME_INTERPOLATION_UNSUPPORTED",
     /**
      * 接入方未授予相机权限。
      */
@@ -382,9 +520,6 @@ type XmaxErrorListener = (error: XmaxError) => void;
  * 表示 SDK 抛出或回调给接入方的统一错误。
  */
 declare class XmaxError extends Error {
-    /**
-     * 错误信息
-     */
     /**
      * SDK 统一错误码。
      */
@@ -417,84 +552,6 @@ 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;
-    });
-}
-
 /**
  * 实时业务连接状态。
  */
@@ -520,7 +577,12 @@ declare enum RealtimeConnectionState {
      */
     connected = "Connected",
     /**
-     * 实时连接已建立且生成任务正在运行。
+     * 正在启动生成或等待 SDK 视频视图完成首帧及渲染预热。
+     * startGeneration 返回远端流后仍可能保持此状态，接入方需挂载视频视图。
+     */
+    starting = "Starting",
+    /**
+     * 生成任务正在运行，SDK 视频视图已完成渲染预热并开始展示画面。
      */
     generating = "Generating",
     /**
@@ -539,6 +601,9 @@ type RealtimeReason = {
     kind: "failure";
     error: XmaxError;
 };
+/**
+ * 正常操作、画面方向变化和错误对应的状态原因。
+ */
 declare const RealtimeReason: {
     normal: RealtimeReason;
     orientationChanged: RealtimeReason;
@@ -547,26 +612,35 @@ declare const RealtimeReason: {
      */
     failure(error: XmaxError): RealtimeReason;
 };
+/**
+ * 实时状态快照的生命周期、业务标识和变化原因。
+ */
 interface RealtimeStateInit {
+    /**
+     * 当前实时连接生命周期状态。
+     */
     connectionState: RealtimeConnectionState;
+    /**
+     * 业务会话标识。
+     */
     sessionID?: string;
+    /**
+     * 当前生成任务标识。
+     */
     taskID?: string;
+    /**
+     * 当前操作的结束或变更原因。
+     */
     reason?: RealtimeReason;
 }
 /**
  * 实时业务当前状态快照。
  */
 declare class RealtimeState {
-    /**
-     * 连接生命周期
-     */
     /**
      * 当前连接生命周期状态。
      */
     readonly connectionState: RealtimeConnectionState;
-    /**
-     * 业务标识
-     */
     /**
      * 当前或最近一次实时 Session 标识。
      */
@@ -575,20 +649,12 @@ declare class RealtimeState {
      * 当前生成任务标识。
      */
     readonly taskID?: string;
-    /**
-     * 状态变化原因
-     */
     /**
      * 进入当前状态的原因；正常开始新的操作时清空。
      */
     readonly reason?: RealtimeReason;
     /**
      * 创建实时状态快照。
-     *
-     * @param init.connectionState 当前连接生命周期状态。
-     * @param init.sessionID 当前或最近一次实时 Session 标识。
-     * @param init.taskID 当前生成任务标识。
-     * @param init.reason 状态变化原因，默认无。
      */
     constructor(init: RealtimeStateInit);
     /**
@@ -604,11 +670,11 @@ declare class RealtimeState {
 type RealtimeStateListener = (state: RealtimeState) => void;
 
 /**
- * 一次相机启动的耗时快照，单位为毫秒；undefined 表示该阶段尚未完成或未启用。
- * 新一轮打开摄像头时重置；失败、关闭或断开后保留已完成的值。
+ * 一次媒体启动的耗时快照，单位为毫秒；undefined 表示该阶段尚未完成或未启用。
+ * 新一轮创建媒体源时重置；失败、关闭或断开后保留已完成的值。
  * 仅预览时不产生首帧和总耗时；预览后手动启动生成的等待计入总耗时。
  */
-interface RealtimeLaunchTiming {
+interface RealtimeTiming {
     /**
      * 开始打开摄像头到相机流创建完成（包含权限等待）。
      */
@@ -619,71 +685,97 @@ 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;
 }
 /**
  * 阶段完成时提供完整快照；不支持帧回调的浏览器以 playing 近似首帧。
  */
-type RealtimeLaunchTimingListener = (timing: RealtimeLaunchTiming) => void;
+type RealtimeTimingListener = (timing: RealtimeTiming) => void;
 
 /**
- * 视频流实际运行统计；缺失或无效指标为 undefined。
+ * 上下行视频统计共用的媒体指标；缺失或无效指标为 undefined。
  */
 interface VideoStatistics {
     /**
-     * 本端视频上行丢包率，单位 %；厂商未提供时为空。
+     * 视频实际宽度，单位为像素；本地为发送尺寸，远端为接收尺寸。
      */
-    readonly uplinkLossPercent?: number;
     readonly width?: number;
-    readonly height?: number;
     /**
-     * 实际帧率，单位 fps。
+     * 视频实际高度，单位为像素；本地为发送尺寸，远端为接收尺寸。
      */
-    readonly frameRate?: number;
+    readonly height?: number;
     /**
      * 实际码率，单位 kbps。
      */
     readonly bitrateKbps?: number;
 }
+/**
+ * 本地视频流的上行运行统计。
+ */
+interface UplinkVideoStatistics extends VideoStatistics {
+    /**
+     * 实际采集帧率，单位 fps。
+     */
+    readonly captureFrameRate?: number;
+    /**
+     * 实际编码帧率，单位 fps；厂商未提供时为空，不以发送帧率替代。
+     */
+    readonly encodeFrameRate?: number;
+    /**
+     * 实际发送帧率，单位 fps。
+     */
+    readonly sendFrameRate?: number;
+    /**
+     * 本端到 RTC 云端的视频上行丢包率，范围为 0～100，单位 %。
+     */
+    readonly packetLossPercent?: number;
+}
 /**
  * undefined 表示当前没有可用统计（尚未发布、断开或停止）。
  */
-type VideoStatisticsListener = (statistics: VideoStatistics | undefined) => void;
+type UplinkVideoStatisticsListener = (statistics: UplinkVideoStatistics | undefined) => void;
 /**
  * 一路远端主视频流的接收统计。
  */
-interface RemoteVideoStatistics extends VideoStatistics {
-    readonly userID: string;
+interface DownlinkVideoStatistics extends VideoStatistics {
     /**
-     * 本端 SDK 到 RTC 云端的往返延迟，单位 ms；不是与远端用户之间的 RTT。
+     * RTC 用户标识。
      */
-    readonly rttMs?: number;
+    readonly userID: string;
     /**
-     * 本端 SDK 到 RTC 云端的上行丢包率，单位 %，不是结果流的发送端丢包率。
+     * 实际解码帧率，单位 fps。
      */
-    readonly uplinkLossPercent?: number;
+    readonly decodeFrameRate?: number;
     /**
-     * RTC 云端到本端 SDK 的下行丢包率，单位 %。
+     * RTC 渲染帧率，单位 fps。
      */
-    readonly downlinkLossPercent?: number;
+    readonly renderFrameRate?: number;
     /**
-     * 当前远端视频流的播放缓冲延迟，单位 ms；Agora 未提供时为空。
+     * RTC 云端到本端 SDK 的视频下行丢包率，范围为 0～100，单位 %。
      */
-    readonly jitterBufferDelayMs?: number;
+    readonly packetLossPercent?: number;
     /**
      * RTC 媒体端到端延迟估算值，单位 ms；不代表完整 AI 处理链路耗时。
      * 采用各厂商原生口径，Agora end2EndDelay 不包含编码与解码耗时。
@@ -693,16 +785,173 @@ interface RemoteVideoStatistics extends VideoStatistics {
 /**
  * undefined 表示当前结果流没有统计或已被清理。
  */
-type RemoteVideoStatisticsListener = (statistics: RemoteVideoStatistics | undefined) => void;
+type DownlinkVideoStatisticsListener = (statistics: DownlinkVideoStatistics | undefined) => void;
+
+/**
+ * 摄像头分辨率快捷选项；实际支持范围由模型决定。
+ */
+declare enum RealtimeCameraPreset {
+    /**
+     * 16:9 横向画面。
+     */
+    resolution1920x1080 = "1920x1080",
+    /**
+     * 9:16 竖向画面。
+     */
+    resolution1080x1920 = "1080x1920",
+    /**
+     * 1:1 正方形画面。
+     */
+    resolution1408x1408 = "1408x1408",
+    /**
+     * 3:4 竖向画面。
+     */
+    resolution1152x1536 = "1152x1536",
+    /**
+     * 4:3 横向画面。
+     */
+    resolution1536x1152 = "1536x1152"
+}
+/**
+ * 读取预设的像素宽高，不包含帧率和码率配置。
+ */
+declare function cameraPresetSize(preset: RealtimeCameraPreset): ModelSize;
+
+/**
+ * 实时传输档位；L1 质量最高，L5 最节省带宽，与网络质量评级无关。
+ */
+declare enum RealtimeQualityLevel {
+    /**
+     * 保留媒体基准尺寸。
+     */
+    l1 = 1,
+    /**
+     * 目标宽高为媒体基准的 90%。
+     */
+    l2 = 2,
+    /**
+     * 目标宽高为媒体基准的 75%。
+     */
+    l3 = 3,
+    /**
+     * 目标宽高为媒体基准的 60%。
+     */
+    l4 = 4,
+    /**
+     * 目标宽高为媒体基准的 50%，上行帧率上限为 16 fps。
+     */
+    l5 = 5
+}
+
+/**
+ * 外部 PCM 帧的只读输入契约，浏览器 AudioData 可直接传入。
+ * 使用结构类型，避免要求接入方额外安装 WebCodecs 全局类型。
+ */
+interface RealtimeExternalAudioFrame {
+    /**
+     * 共用源时间轴上的微秒时间戳及固定 PCM 规格。
+     */
+    readonly timestamp: number;
+    readonly sampleRate: number;
+    readonly numberOfChannels: number;
+    readonly numberOfFrames: number;
+    readonly format: string | null;
+    /**
+     * 将指定声道复制为平面浮点 PCM；返回后 SDK 不再访问原始样本。
+     */
+    copyTo(destination: Float32Array, options: {
+        planeIndex: number;
+        format: "f32-planar";
+    }): void;
+}
+
+/**
+ * 外部帧源与兼容视频轨入口二选一，禁止混用两套所有权和生命周期。
+ */
+type RealtimeExternalVideoStreamOptions = {
+    source: RealtimeExternalVideoSource;
+    videoTrack?: never;
+    videoFormat?: never;
+} | {
+    videoTrack: MediaStreamTrack;
+    videoFormat: RealtimeVideoFormat;
+    source?: never;
+};
+/**
+ * 接入方拥有的外部采集、解码或处理源；SDK 不申请设备权限，也不播放输入音频。
+ * videoFormat 和 hasAudio 在一次绑定内保持不变，音视频时间戳使用同一单调时间轴。
+ */
+interface RealtimeExternalVideoSource {
+    /**
+     * 原始视频尺寸、帧率及编码配置；方向和镜像由接入方处理到像素中。
+     */
+    readonly videoFormat: RealtimeVideoFormat;
+    /**
+     * 是否通过 sink 提交音频，默认 false。
+     */
+    readonly hasAudio?: boolean;
+    /**
+     * 安装帧回调并在源可交付后返回；不要等待首帧或生成开始。
+     * 接入方按实时节奏提交，断开连接时可继续送视频以维持预览。
+     */
+    start(sink: RealtimeExternalFrameSink): Promise<void>;
+    /**
+     * 停止交付并解除 sink 引用，须可重复调用；采集设备及播放器仍归接入方管理。
+     */
+    stop(): Promise<void>;
+}
+/**
+ * 一次外部源绑定的输入端；可在提交返回后 close 原帧，SDK 不接管原帧所有权。
+ * VideoFrame.timestamp 和 AudioData.timestamp 均为非负微秒时间，不能跨循环或 seek 回退。
+ */
+interface RealtimeExternalFrameSink {
+    /**
+     * 经过像素面积约束和 4 对齐的固定媒体规格；提交时仍使用 source.videoFormat 的尺寸。
+     */
+    readonly videoFormat: RealtimeVideoFormat;
+    /**
+     * 是否接受输入；断开时仍为 true，解绑或源失败后永久变为 false。
+     */
+    readonly isRequestingFrames: boolean;
+    /**
+     * 提交原始尺寸的视频帧；SDK 保留副本并缩放到媒体规格，不保证交付每个输入帧。
+     * 重复、回退或无效时间戳被忽略。输入需按实时节奏送达，提前量不得超过两秒。
+     */
+    pushVideo(frame: VideoFrame): void;
+    /**
+     * 提交解码后的 PCM，仅 hasAudio=true 时接受；不接收压缩音频。
+     * 支持 8–192 kHz、1–8 声道，单包不超过一秒；格式在一次绑定内保持不变。
+     * SDK 复制并混成单声道，经 AudioWorklet 重采样和调度；仅发布期间上传，不缓存待重连。
+     * 音频重叠或无效时间戳被忽略，间断在浏览器连续音轨中输出静音，不压缩时间轴。
+     */
+    pushAudio(frame: RealtimeExternalAudioFrame): void;
+    /**
+     * 上报不可恢复的采集或处理错误；SDK 结束连接并释放本地流。
+     */
+    reportError(error: Error): void;
+}
 
 /**
  * 定义 SDK 对接入方提供的实时媒体与生成控制能力。
  */
 interface XmaxRealtimeManaging {
     /**
-     * 监听录制完成、中断或失败；传入 undefined 清除监听，不停止正在进行的录制。
+     * 观察当前生成结果的原始 Web 音视频轨道，立即回放当前绑定。
+     * 不依赖 WebCodecs；适用于 MediaRecorder 等原生媒体流处理。
+     * 轨道仅借用；需要停止或修改时应先 clone()，不得停止 SDK 的原始轨道。
+     * 无结果流时回调 undefined；传 undefined 取消监听，不影响订阅、音量或生成。
+     * 可与原始帧监听并存，close() 时自动清除。
      */
-    setRecordingListener(listener?: RealtimeRecordingListener): void;
+    setRemoteMediaTracksListener(listener?: (tracks?: RemoteMediaTracks) => void): void;
+    /**
+     * 监听当前结果流的原始解码视频和播放音量处理前的 PCM 音频。
+     * 两轨共用接收端呈现时间轴，单位为微秒；按时间戳同步，不按回调到达时间配对。
+     * 视频帧交付后由接入方 close()；回调须保持轻量，队列超限或换流会标记不连续。
+     * 从用户手势调用并等待准备完成；不支持的浏览器或 RTC 平台会拒绝，不终止生成。
+     * 可在生成前或生成中设置；undefined 取消并释放资源，不改变音量、订阅和生成任务。
+     * 浏览器呈现回调可能漏帧，不保证交付全部接收或解码帧；没有音轨时不补静音包。
+     */
+    setRemoteMediaFrameListener(listener?: RealtimeMediaFrameListener): Promise<void>;
     /**
      * 实时能力配置。
      */
@@ -712,23 +961,46 @@ interface XmaxRealtimeManaging {
      */
     readonly currentState: RealtimeState;
     /**
-     * 插帧功能开关；不随首帧等待、跳帧或视图挂载变化，不支持或故障降级时关闭。
+     * 当前摄像头媒体规格，不随上行调档变化；没有摄像头流时为空。
+     */
+    readonly currentCameraVideoFormat?: RealtimeVideoFormat;
+    /**
+     * 当前摄像头尺寸匹配的预设；没有摄像头或尺寸未匹配预设时为空。
+     */
+    readonly currentCameraPreset?: RealtimeCameraPreset;
+    /**
+     * 更新预览就绪且未连接的摄像头规格，保留 SDK 轨道与视图绑定。
+     * 传入预设时保留当前帧率、码率和编码偏好，尺寸仍按模型规则解析。
+     */
+    updateCameraFormat(format: RealtimeVideoFormat | RealtimeCameraPreset): Promise<void>;
+    /**
+     * 当前连接成功应用的上行档位；未连接、断开或没有本地上行时为空。
+     */
+    readonly uplinkQualityLevel?: RealtimeQualityLevel;
+    /**
+     * 当前连接成功提交的下行档位；尚未开始生成、未连接或断开时为空，实际回传可能稍晚生效。
+     */
+    readonly downlinkQualityLevel?: RealtimeQualityLevel;
+    /**
+     * 在生成中指定上行编码档位，不改变媒体采集规格和生成画布。
+     * Agora、TRTC 的自动调档从新档位继续；VeRTC 仅应用手动档位。
      */
-    readonly isFrameInterpolationEnabled: boolean;
+    setUplinkQualityLevel(level: RealtimeQualityLevel): Promise<void>;
     /**
-     * 切换客户端插帧，不改变回传分辨率或重启任务。不支持时抛错且保留配置。
+     * 在生成中指定下行回传档位；已启用自动调档时，从新档位继续判断。
+     * 发送成功表示请求已提交，不代表服务端已经返回新尺寸。
      */
-    setFrameInterpolationEnabled(enabled: boolean): Promise<void>;
+    setDownlinkQualityLevel(level: RealtimeQualityLevel): Promise<void>;
     /**
-     * 手动升/降一档上行配置；仅支持正在生成的 Agora、TRTC 会话。
-     * Agora 调整分辨率、帧率和编码码率；TRTC 临时只调整帧率，保留尺寸和码率配置。
-     * 保留原始 L1 基准，不改变下行尺寸；自动调档仍保持开启。
+     * 手动升/降一档上行配置，需要正在生成且存在本地上行。
+     * Agora、VeRTC 调整分辨率、帧率和编码码率；TRTC 只调整帧率，保留尺寸和码率配置。
+     * 保留原始 L1 基准，不改变下行尺寸；已启用的自动调档保持开启。
      * @param direction 升一档或降一档；到达 L1/L5 边界时不重复应用。
      */
     adjustUplinkQuality(direction: "upgrade" | "downgrade"): Promise<void>;
     /**
-     * 手动升/降一档下行输出尺寸，便于调试 change_target_size；仅支持正在生成的 Agora、TRTC 会话。
-     * 仅改变分辨率，成功发送后同步目标档位与插帧尺寸；自动调档仍保持开启。
+     * 手动升/降一档下行输出尺寸，需要正在生成。
+     * 仅改变分辨率，成功发送后同步目标档位；已启用的自动调档保持开启。
      * 到达 L1/L5 边界时不重复发送；发送成功不代表服务端已生效。
      */
     adjustDownlinkQuality(direction: "upgrade" | "downgrade"): Promise<void>;
@@ -746,29 +1018,30 @@ interface XmaxRealtimeManaging {
      */
     setStateListener(listener?: RealtimeStateListener): Promise<void>;
     /**
-     * 监听 TRTC 上下行网络质量和 RTT；立即回放最新快照，断开后回调 undefined。
+     * 监听上下行网络质量；立即回放最新快照，尚无采样或断开后回调 undefined。
      * 独立于日志和远端生成流；传入 undefined 取消监听，监听器异常不影响主流程。
      */
-    setNetworkStatisticsListener(listener?: NetworkStatisticsListener): Promise<void>;
+    setNetworkQualityListener(listener?: RealtimeNetworkQualityListener): Promise<void>;
     /**
      * 监听启动耗时；立即回放当前快照，每完成一个阶段再次回调。
-     * 新一轮打开摄像头时重置；失败或终止后冻结，更新生成条件不重置。
+     * 新一轮创建媒体源时重置；失败或终止后冻结，更新生成条件不重置。
      * 首帧统计需要将远端轨道绑定到 SDK 视频视图，且不会阻塞 startGeneration。
      * 传入 undefined 清除监听器；监听器异常不影响生成流程。
+     * 开启 performance 日志后，渲染预热完成时另向 console.info 输出启动汇总，不依赖监听器。
      */
-    setLaunchTimingListener(listener?: RealtimeLaunchTimingListener): Promise<void>;
+    setTimingListener(listener?: RealtimeTimingListener): Promise<void>;
     /**
-     * 监听本地主视频流实际分辨率、帧率及码率（kbps），独立于日志开关。
+     * 监听上行分辨率、采集/编码/发送帧率、码率和丢包率，独立于日志开关。
      * 设置后立即回放最新快照；未取得数据或停止/断开时回调 undefined。
      * 传入 undefined 取消监听；监听器异常不影响生成流程。
      */
-    setLocalVideoStatisticsListener(listener?: VideoStatisticsListener): Promise<void>;
+    setUplinkVideoStatisticsListener(listener?: UplinkVideoStatisticsListener): Promise<void>;
     /**
-     * 监听当前生成结果流的分辨率、帧率、码率、云端 RTT 和媒体 E2E 估算值。
+     * 监听下行分辨率、解码/RTC 渲染帧率、码率、丢包率和媒体 E2E 估算值。
      * 独立于日志开关；立即回放最新快照，流消失或断开时回调 undefined。
      * 传入 undefined 取消监听；监听器异常不影响生成流程。
      */
-    setRemoteVideoStatisticsListener(listener?: RemoteVideoStatisticsListener): Promise<void>;
+    setDownlinkVideoStatisticsListener(listener?: DownlinkVideoStatisticsListener): Promise<void>;
     /**
      * 设置本地媒体预览音量。
      * @throws 音量超出有效范围时抛出错误。
@@ -786,6 +1059,7 @@ interface XmaxRealtimeManaging {
      * 将返回的轨道绑定到预览视图；收到有效帧且视图已绑定后进入 `ready`。
      *
      * @param options.videoFormat 旋转后的目标规格，尺寸按模型规则解析。
+     * @param options.preset 替代 videoFormat，使用模型支持的摄像头预设和推荐帧率；两者必须且只能提供一个。
      * @param options.position 前置或后置摄像头。
      * @param options.useMicrophone 是否采集并发布麦克风音频。
      * @param options.rotation 输入帧顺时针旋转角度，默认 0；非零角度目前仅支持 Agora，预览和上传均校正方向，镜像保持独立。
@@ -794,34 +1068,24 @@ interface XmaxRealtimeManaging {
      * @throws 模型不支持相机输入、配置无效、权限或采集启动失败时抛出错误。
      */
     createLocalCameraStream(options: {
-        videoFormat: RealtimeVideoFormat;
         position: CameraPosition;
         useMicrophone: boolean;
         rotation?: CameraRotation;
         enableFrameValidation?: boolean;
-    }): Promise<RealtimeMediaStream>;
-    /**
-     * 创建服务端直接读取的 HTTP/HTTPS 网络视频源，不采集或发布本地音视频。
-     * 本地预览静音播放一次，独立于服务端进度；创建源不会开始生成。
-     * 地址必须可由服务端直接访问，不转发浏览器 Cookie 或自定义鉴权头。
-     * @param options.url 服务端可直接访问的 HTTP/HTTPS 视频地址。
-     * @param options.videoFormat 模型输入及生成画面规格，不是上行编码参数。
-     * @param options.sampleMethod 服务端采样方式，默认 time。
-     * @param options.onFinish 当前任务收到服务端完成消息且生成就绪后调用一次，不代表尾帧已播放完。
-     * @throws 地址、格式无效或已有活动媒体源时抛错；close 释放源，disconnect 保留预览。
-     */
-    createNetworkVideoStream(options: {
-        url: string;
+    } & ({
         videoFormat: RealtimeVideoFormat;
-        sampleMethod?: RealtimeVideoSampleMethod;
-        onFinish?: () => void;
-    }): Promise<RealtimeMediaStream>;
+        preset?: never;
+    } | {
+        preset: RealtimeCameraPreset;
+        videoFormat?: never;
+    })): Promise<RealtimeMediaStream>;
     /**
      * 从本地 File/Blob 创建文件视频源，支持 TRTC、Agora 和 VeRTC，不访问摄像头或麦克风。
-     * 通过 Canvas 等比缩放补黑边，文件音频独立上行，本地预览始终静音。
+     * Canvas 保留完整内容并按媒体尺寸规则缩放，文件音频独立上行，本地预览始终静音。
+     * SDK 单独选择模型生成画布，仅在媒体与画布比例不一致时启用服务端 contain 补边。
      * 应从用户点击事件直接调用以解锁播放；创建后停在首帧，startGeneration 时开始播放。
      * @param options.file 包含可解码视频的本地 File 或 Blob。
-     * @param options.videoFormat 期望的视频规格；尺寸自动匹配最接近宽高比的模型档位，等距时优先横屏。
+     * @param options.videoFormat 帧率及编码配置；宽高保留兼容入参，实际媒体尺寸从文件读取。
      * @param options.loop 是否循环播放文件音视频，默认 true。
      * @param options.includeAudio 是否发送文件音频，默认 true；无音轨文件输出静音，false 不创建音频轨。
      * @throws 提供方不支持、文件/格式无效、浏览器无法解码或播放受限时抛错。
@@ -834,10 +1098,11 @@ interface XmaxRealtimeManaging {
     }): Promise<RealtimeMediaStream>;
     /**
      * 从本地 File/Blob 创建图片视频流，支持 TRTC、Agora 和 VeRTC。
-     * 等比缩放并居中补黑边，持续发送同一静止画面，不上传文件、不采集摄像头或麦克风。
+     * 保留完整内容并按媒体尺寸规则缩放，持续发送同一静止画面，不上传文件、不采集摄像头或麦克风。
+     * SDK 单独选择模型生成画布，仅在媒体与画布比例不一致时启用服务端 contain 补边。
      * 创建后可直接预览，仍需调用 startGeneration 开始生成；disconnect 保留图片源，close 释放全部资源。
      * @param options.file 包含浏览器可解码图片的本地 File 或 Blob；动图仅取解码时的静止快照。
-     * @param options.videoFormat 期望的视频规格；尺寸自动匹配最接近宽高比的模型档位，等距时优先横屏。
+     * @param options.videoFormat 帧率及编码配置；宽高保留兼容入参，实际媒体尺寸从图片读取。
      * @throws 文件或格式无效、浏览器无法解码、Canvas 采集不可用或已有活动源时抛错。
      */
     createLocalImageStream(options: {
@@ -845,25 +1110,31 @@ interface XmaxRealtimeManaging {
         videoFormat: RealtimeVideoFormat;
     }): Promise<RealtimeMediaStream>;
     /**
-     * 接收用户自行采集或处理的实时视频轨，仅视频，不采集或发送音频。
-     * 不要求绑定 SDK 预览；旋转、裁剪及本地预览由调用方负责，后端 mirror 固定 false。
-     * SDK 持有轨道副本：disconnect 保留输入，close 释放副本，不停止调用方原始轨道。
-     * 副本共享底层媒体源；调用方仍负责停止原始采集。设备源结束时 SDK 上报错误并关闭。
-     * @param options.videoTrack 用户自行采集或处理的 live 视频轨，原始轨道归调用方所有。
-     * @param options.videoFormat 期望的上传及生成规格，须符合模型规则；不代表修改输入像素。
-     * @throws 非 live 视频轨、不支持的格式、已有活动媒体源或 RTC 初始化失败时抛错。
+     * 接收外部帧源，或兼容仅视频的原生轨入口；不申请设备权限，不播放输入音频。
+     * 传 source 时调用 start(sink)，支持可选 PCM；创建完成即 ready，不等待首帧。
+     * 外部帧按媒体规则限制面积并按 4 对齐，SDK 缩放并提供预览；方向和镜像由接入方负责。
+     * 传 videoTrack/videoFormat 时仅克隆视频轨，保持原有行为，不处理其像素或创建预览绑定。
+     * disconnect 保留源和预览，但丢弃音频；stopExternalVideoStream 或 close 使旧 sink 失效并调用 source.stop。
+     * 有音频时需从用户手势调用以解锁 AudioContext，要求安全上下文及 AudioWorklet。
+     * @param options.source 接入方拥有的外部音视频帧源，与 videoTrack/videoFormat 二选一。
+     * @param options.videoTrack 兼容入口：接入方拥有的 live 视频轨。
+     * @param options.videoFormat 兼容入口：原视频轨的尺寸、帧率及编码配置。
+     * @throws 配置无效、已有活动媒体、源启动或 RTC 准备失败时抛错并清理本次绑定。
      */
-    createExternalVideoStream(options: {
-        videoTrack: MediaStreamTrack;
-        videoFormat: RealtimeVideoFormat;
-    }): Promise<RealtimeMediaStream>;
+    createExternalVideoStream(options: RealtimeExternalVideoStreamOptions): Promise<RealtimeMediaStream>;
+    /**
+     * 未连接时解绑外部源，清空预览并释放 SDK 输出，不接管接入方采集设备。
+     * 已连接时请先 disconnect；对其他媒体源不做操作。
+     */
+    stopExternalVideoStream(): Promise<void>;
     /**
      * 更新当前本地流的上行视频格式，立即应用于 RTC 编码器，不重连或重启生成。
      * 传入完整格式；未指定的码率和编码偏好按 RealtimeVideoFormat 默认规则解析。
-     * 成功后更新本地轨道的 videoFormat，后续重连继续使用该格式。
-     * 模型生成及远端插帧仍使用创建本地流时的格式；此接口不改变生成尺寸。
+     * 尺寸向下做 4 对齐，优先保持精确比例；帧率、码率及编码偏好保持传入配置。
+     * 成功后本地轨道的 videoFormat 记录对齐后的格式，后续重连继续使用该格式。
+     * 模型生成仍使用创建本地流时的格式；此接口不改变生成尺寸。
      * 实际发送规格受设备、浏览器和网络影响，应通过统计回调确认。
-     * 上行自适应以本次成功应用的完整格式作为新的 L1 基准；Agora 按档位缩放尺寸和帧率，TRTC 临时仅调帧率。
+     * 上行自适应以本次成功应用的完整格式作为新的 L1 基准；Agora 按档位缩放尺寸和帧率，TRTC 仅调帧率。
      *
      * @param videoFormat 本次完整的上行尺寸、帧率和编码配置。
      * @throws 无本地相机、外部、图片或文件视频流、其他操作进行中、参数无效或 RTC 更新失败时抛错。
@@ -892,11 +1163,11 @@ interface XmaxRealtimeManaging {
     /**
      * 使用当前 Manager 创建的本地流建立实时连接。
      *
-     * 创建实时会话、加入 RTC 房间并启动会话心跳；摄像头源发布本地流，网络视频源仅接收。
+     * 创建实时会话、加入 RTC 房间、发布本地媒体并启动会话心跳。
      * 启用帧检测时，发布前并行等待相机预热（固定 200ms），避免把黑帧推给 RTC。
      * 返回的远端媒体流在生成开始后承载远端生成画面。
      *
-     * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地图片、本地视频文件或网络视频源。
+     * @param localStream 由当前 Manager 创建的摄像头、外部视频轨、本地图片或本地视频文件。
      * @returns 远端生成结果占位的媒体流。
      * @throws 本地流不属于当前 Manager、已有活动连接、会话创建或进房
      * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
@@ -916,14 +1187,14 @@ interface XmaxRealtimeManaging {
      *
      * 尚未连接时先建立实时连接；已在生成时默认更新条件，restart 为 true 时重新开始生成。
      * 首次生成必须提供条件上下文，之后缺省时复用最近一次缓存的上下文。
+     * 返回后请将远端流挂载到 SDK 视频视图；首帧及渲染预热完成后状态才进入 generating。
      *
-     * @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 承载远端生成画面的媒体流。
+     * @returns 可挂载的远端媒体流，不等待渲染预热；展示就绪以 generating 状态为准。
      * @throws extraParams 包含非 JSON 数据、循环引用或 SDK 保留字段时，在连接或更新前抛出 invalidConfiguration。
      * @throws 本地流不属于当前 Manager、缺少可用的条件上下文、信令发送
      * 或生成确认失败时抛出错误；失败时自动停止生成任务并释放连接资源。
@@ -934,7 +1205,6 @@ interface XmaxRealtimeManaging {
         restart?: boolean;
         faceRestoration?: boolean;
         extraParams?: RealtimeExtraParams;
-        record?: boolean;
     }): Promise<RealtimeMediaStream>;
 }
 
@@ -955,18 +1225,25 @@ declare enum XmaxEnvironment {
  * 环境对应的 Xmax API Base URL。
  */
 declare function apiBaseURL(environment: XmaxEnvironment): string;
+/**
+ * 环境对应的实时会话 API 地址。
+ */
+declare function realtimeApiBaseURL(environment: XmaxEnvironment): string;
 
 /**
  * 控制 XmaxSDK 输出的日志类型（位掩码，可组合）。
  */
 declare enum XmaxLoggerOption {
+    /**
+     * 关闭全部 SDK 日志输出。
+     */
     none = 0,
     /**
      * Room、API、Realtime、Storage 等业务运行日志。
      */
     business = 1,
     /**
-     * RTC 网络质量和音视频运行统计，输出到 console.info。
+     * 启动耗时、RTC 网络质量和音视频运行统计，输出到 console.info。
      */
     performance = 2,
     /**
@@ -984,14 +1261,41 @@ declare class XmaxLogger {
      * 分类日志
      */
     static readonly realtime: XmaxLogger;
+    /**
+     * RTC 引擎、进退房和媒体传输日志。
+     */
     static readonly rtc: XmaxLogger;
+    /**
+     * 本地媒体准备与释放日志。
+     */
     static readonly media: XmaxLogger;
+    /**
+     * API 请求及响应日志。
+     */
     static readonly api: XmaxLogger;
+    /**
+     * 文件上传与下载日志。
+     */
     static readonly storage: XmaxLogger;
+    /**
+     * 房间消息和心跳日志。
+     */
     static readonly room: XmaxLogger;
+    /**
+     * 流发布、订阅及生成控制日志。
+     */
     static readonly stream: XmaxLogger;
+    /**
+     * 视频视图与渲染管线日志。
+     */
     static readonly render: XmaxLogger;
+    /**
+     * 触点采样和轨迹交互日志。
+     */
     static readonly interaction: XmaxLogger;
+    /**
+     * 摄像头和麦克风权限日志。
+     */
     static readonly permission: XmaxLogger;
     /**
      * 日志类别
@@ -1038,6 +1342,9 @@ declare class XmaxLogger {
     private log;
 }
 
+/**
+ * SDK 的身份、环境和日志选项。
+ */
 interface XmaxConfigurationInit {
     /**
      * 调用 Xmax 服务使用的 API Key。
@@ -1056,9 +1363,6 @@ interface XmaxConfigurationInit {
  * SDK 全局配置。
  */
 declare class XmaxConfiguration {
-    /**
-     * 服务身份与环境
-     */
     /**
      * 调用 Xmax 服务使用的 API Key。
      */
@@ -1067,19 +1371,12 @@ declare class XmaxConfiguration {
      * SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。
      */
     readonly environment: XmaxEnvironment;
-    /**
-     * 日志配置
-     */
     /**
      * SDK 输出的日志类型；默认为不输出日志。
      */
     readonly loggerOptions: XmaxLoggerOption;
     /**
-     * 创建 SDK 全局配置。
-     *
-     * @param init.apiKey 调用 Xmax 服务使用的 API Key。
-     * @param init.environment SDK 连接的服务环境；默认为国内环境。
-     * @param init.loggerOptions SDK 输出的日志类型；默认为空。
+     * 清理 API Key 首尾空白并补全环境和日志默认值；有效性检查由 validate 执行。
      */
     constructor(init: XmaxConfigurationInit);
     /**
@@ -1093,16 +1390,34 @@ declare class XmaxConfiguration {
  * 非实时视频的输出质量。
  */
 declare enum NonRealtimeQuality {
+    /**
+     * 标准清晰度输出。
+     */
     sd = "sd",
+    /**
+     * 高清输出。
+     */
     hd = "hd"
 }
 /**
  * 服务端任务状态；上传进度不属于任务状态。
  */
 declare enum NonRealtimeTaskStatus {
+    /**
+     * 任务已提交，等待服务端处理。
+     */
     submitted = "submitted",
+    /**
+     * 服务端正在处理任务。
+     */
     processing = "processing",
+    /**
+     * 任务处理完成。
+     */
     completed = "completed",
+    /**
+     * 任务处理失败。
+     */
     error = "error"
 }
 /**
@@ -1138,16 +1453,49 @@ interface NonRealtimeTaskOptions {
  * 非实时生成结果；缺失或 null 的服务端字段规范化为 undefined。
  */
 interface NonRealtimeResult {
+    /**
+     * 生成结果文件的访问 URL。
+     */
     readonly url?: string;
+    /**
+     * 服务端上传生成结果时返回的错误说明。
+     */
     readonly uploadError?: string;
+    /**
+     * 生成结果的上传状态。
+     */
     readonly uploadStatus?: string;
+    /**
+     * 服务端结果收尾耗时，单位为毫秒。
+     */
     readonly finalizeDurationMs?: number;
+    /**
+     * 服务端使用的压缩等级。
+     */
     readonly compressionLevel?: string;
+    /**
+     * 结果视频的帧数。
+     */
     readonly frameCount?: number;
+    /**
+     * 结果视频帧率，单位为 fps。
+     */
     readonly fps?: number;
+    /**
+     * 结果视频时长，单位为毫秒。
+     */
     readonly durationMs?: number;
+    /**
+     * 结果文件大小，单位为字节。
+     */
     readonly fileSizeBytes?: number;
+    /**
+     * 服务端处理时丢弃的帧数。
+     */
     readonly droppedFrameCount?: number;
+    /**
+     * 结果压缩前的文件大小，单位为字节。
+     */
     readonly originalFileSizeBytes?: number;
 }
 /**
@@ -1155,23 +1503,77 @@ interface NonRealtimeResult {
  * 时间戳保持服务端原始字符串，不推断时区。
  */
 interface NonRealtimeTask {
+    /**
+     * 非实时任务标识，用于查询和恢复任务。
+     */
     readonly uid: string;
+    /**
+     * 服务端返回的运行状态。
+     */
     readonly status: NonRealtimeTaskStatus;
+    /**
+     * 业务用户标识。
+     */
     readonly userUid?: string;
+    /**
+     * 本次视频生成使用的文字指令。
+     */
     readonly prompt?: string;
+    /**
+     * 已上传源视频的 URL。
+     */
     readonly videoPath?: string;
+    /**
+     * 已上传参考图片的 URL。
+     */
     readonly referencePath?: string;
+    /**
+     * 服务端任务处理器标识。
+     */
     readonly processorId?: string;
+    /**
+     * 生成结果使用的输出质量。
+     */
     readonly quality?: NonRealtimeQuality;
+    /**
+     * 提交任务时指定的处理帧率，单位为 fps。
+     */
     readonly requestedFps?: number;
+    /**
+     * 服务端最终使用的处理帧率，单位为 fps。
+     */
     readonly resolvedFps?: number;
+    /**
+     * 服务端已执行的重试次数。
+     */
     readonly retryCount?: number;
+    /**
+     * 源视频时长，单位为秒。
+     */
     readonly videoDurationSeconds?: number;
+    /**
+     * 服务端报告的计费时长，单位为秒。
+     */
     readonly billableDurationSeconds?: number;
+    /**
+     * 服务端报告的任务消耗点数。
+     */
     readonly chargePoints?: number;
+    /**
+     * 生成结果的文件和处理信息。
+     */
     readonly result?: NonRealtimeResult;
+    /**
+     * 服务端开始处理任务的时间。
+     */
     readonly processStartTime?: string;
+    /**
+     * 任务创建时间。
+     */
     readonly createTimestamp?: string;
+    /**
+     * 任务最近更新时间。
+     */
     readonly updateTimestamp?: string;
 }
 /**
@@ -1195,9 +1597,21 @@ interface NonRealtimeTaskListOptions {
  * 按创建时间从新到旧排列的任务页。
  */
 interface NonRealtimeTaskPage {
+    /**
+     * 当前页码，从 1 开始。
+     */
     readonly pageNumber: number;
+    /**
+     * 当前页的容量。
+     */
     readonly pageSize: number;
+    /**
+     * 符合查询条件的任务总数。
+     */
     readonly total: number;
+    /**
+     * 当前页中的任务，按创建时间从新到旧排列。
+     */
     readonly list: readonly NonRealtimeTask[];
 }
 
@@ -1260,9 +1674,6 @@ interface XmaxNonRealtimeManaging {
  * SDK 的统一入口，负责创建实时、非实时和媒体服务组件。
  */
 declare class XmaxClient {
-    /**
-     * 客户端配置
-     */
     /**
      * 客户端使用的全局配置。
      */
@@ -1280,7 +1691,7 @@ declare class XmaxClient {
     constructor(configuration: XmaxConfiguration);
     /**
      * 创建实时媒体 Manager。
-     * 模型专用地址优先于环境默认地址，并用于该 Manager 的整个会话生命周期。
+     * 已知模型按环境选择实时会话地址；自定义模型使用测试地址，覆盖整个会话生命周期。
      *
      * @param options 实时生成模型等业务配置。
      * @returns 可用于本地相机预览、实时连接与生成的实时 Manager。
@@ -1294,7 +1705,7 @@ declare class XmaxClient {
     /**
      * 创建媒体处理与能力查询 Service。
      *
-     * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
+     * @param model 媒体输入规则使用的模型，默认为 `x2.1`。
      */
     createMediaService(model?: RealtimeModelName): MediaServicing;
     /**
@@ -1320,8 +1731,7 @@ declare class NonRealtimeTaskError extends XmaxError {
 }
 
 /**
- * 提供模型输入尺寸和平台媒体能力相关的业务规则。
- * 模型输入尺寸与远端插帧能力。
+ * 统一计算本地媒体、生成画布及回传尺寸，并查询平台媒体能力。
  */
 declare class MediaService implements MediaServicing {
     /**
@@ -1330,18 +1740,29 @@ declare class MediaService implements MediaServicing {
     readonly model: RealtimeModelName;
     /**
      * 创建媒体服务。
-     *
-     * @param model 媒体输入规则使用的模型，默认为 `x2.0-trtc`。
      */
     constructor(model?: RealtimeModelName);
     /**
-     * Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。
+     * 解析固定媒体基准：保留完整内容、不放大、限制面积并按 4 对齐。
+     * 摄像头请求尺寸须先匹配模型桶；文件媒体和外部轨道不受模型桶比例限制。
+     *
+     * @param sourceMediaSize 原始媒体尺寸。
+     * @param source 媒体来源，仅摄像头需要校验采集分辨率桶。
+     * @returns 用于固定媒体基准和初始上行编码的尺寸。
+     */
+    resolveMediaSize(sourceMediaSize: ModelSize, source: "camera" | "image" | "video" | "external"): ModelSize;
+    /**
+     * 选择比例最接近的模型生成画布；无固定桶时按模型像素预算和对齐规则计算。
      */
-    resolveFrameInterpolationSize(size: ModelSize): ModelSize;
+    resolveGenerationSize(resolvedMediaSize: ModelSize): ModelSize;
     /**
-     * WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。
+     * 综合下行宽高上限计算回传尺寸，不放大、优先保持比例并按 4 对齐。
      */
-    supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
+    resolveTargetSize(resolvedMediaSize: ModelSize, maximumSize: ModelSize): ModelSize;
+    /**
+     * 拒绝无效或不能安全参与面积计算的媒体像素尺寸。
+     */
+    private validateIntegralSize;
     /**
      * 按模型分辨率档位或像素预算解析输入尺寸，保持宽高比例并对齐；不支持的规格抛错。
      */
@@ -1360,16 +1781,34 @@ declare class MediaService implements MediaServicing {
  * Xmax API 支持的 HTTP 请求方法。
  */
 declare enum ApiMethod {
+    /**
+     * 读取服务端资源。
+     */
     get = "GET",
+    /**
+     * 提交数据或创建资源。
+     */
     post = "POST",
+    /**
+     * 更新服务端资源。
+     */
     put = "PUT",
+    /**
+     * 删除服务端资源。
+     */
     delete = "DELETE"
 }
 /**
  * 请求控制选项；signal 仅取消本地 HTTP 请求，不撤销服务端已执行的操作。
  */
 interface ApiRequestOptions {
+    /**
+     * 取消请求及后续等待的信号。
+     */
     signal?: AbortSignal;
+    /**
+     * 允许页面退出后继续完成符合浏览器限制的请求。
+     */
     keepalive?: boolean;
 }
 /**
@@ -1416,10 +1855,25 @@ interface ApiServicing {
  * 解析后的临时存储配置。
  */
 interface TemporaryStorageConfiguration {
+    /**
+     * 对象存储桶名称。
+     */
     bucket: string;
+    /**
+     * 对象存储桶所在区域。
+     */
     region: string;
+    /**
+     * 对象存储访问域名。
+     */
     endpoint?: string;
+    /**
+     * 上传对象的键名前缀。
+     */
     prefix: string;
+    /**
+     * 对象存储临时鉴权凭据。
+     */
     credentials: {
         accessKeyID: string;
         secretAccessKey: string;
@@ -1454,6 +1908,9 @@ interface StorageObjectClient {
  * 对象存储客户端工厂；生产实现按临时凭证创建 COS 客户端。
  */
 type StorageObjectClientFactory = (configuration: TemporaryStorageConfiguration) => Promise<StorageObjectClient>;
+/**
+ * 对象存储上传所需的接口与客户端依赖。
+ */
 interface StorageServiceOptions {
     /**
      * Xmax API 请求组件。
@@ -1492,6 +1949,9 @@ declare class StorageService implements StorageServicing {
      * 标识生成
      */
     private readonly dateGenerator;
+    /**
+     * 生成上传对象键名中的唯一标识。
+     */
     private readonly identifierGenerator;
     /**
      * 创建存储 Service。
@@ -1561,26 +2021,14 @@ declare class StorageService implements StorageServicing {
     private static nonEmpty;
 }
 
-interface RemoteFrameInterpolationOptions {
-    size: ModelSize;
-    onActiveChange?: (active: boolean) => void;
-    /**
-     * 实际提交画布呈现时通知，参数表示是否为插值帧。
-     */
-    onFramePresented?: (interpolated: boolean) => void;
-    onFailure: (error: unknown) => void;
-}
-
 /**
- * 单轨视频视图（框架无关）。
+ * 显示一路本地或远端视频轨道的实时视频视图（框架无关）。
  *
  * 通过 `attach(to:)` 挂载到任意容器元素；设置 `track` 后自动渲染。
  * 轨道注册了渲染绑定时走绑定管线，否则按 `mediaStreamTrack` 直接渲染。
+ * SDK 远端轨道在首帧后按绑定配置预热，再按视图配置渐入；本地预览不延迟。
  */
-declare class XmaxVideoView {
-    /**
-     * 视图元素
-     */
+declare class XmaxRealtimeVideoView {
     /**
      * 视图根元素（div，内含一个 video 元素）。
      */
@@ -1590,8 +2038,17 @@ declare class XmaxVideoView {
      */
     readonly videoElement: HTMLVideoElement;
     /**
-     * 公共配置
+     * 视频显示层，与触控轨迹层独立。
      */
+    private readonly videoLayer;
+    /**
+     * 首帧预热只影响媒体内容，不影响轨迹交互层。
+     */
+    private readonly warmupLayer;
+    /**
+     * 视频画面是否可见。
+     */
+    private videoVisible;
     /**
      * 首帧实际提交显示时调用（一次性；换轨后重新武装）。
      */
@@ -1600,25 +2057,38 @@ declare class XmaxVideoView {
      * 渲染状态
      */
     private currentTrack?;
+    /**
+     * 画面在视口中的缩放与裁剪方式。
+     */
     private contentMode;
+    /**
+     * 是否对显示画面应用水平镜像。
+     */
     private mirrored;
     /**
      * 首帧显示通知与异步回调版本
      */
     private hasNotifiedFrameDisplay;
+    /**
+     * 视频开始播放时尝试通知首帧就绪。
+     */
     private onPlaying?;
+    /**
+     * 首帧观察回调的取消句柄。
+     */
     private videoFrameCallbackID?;
-    private frameNotificationSequence;
     /**
-     * 远端插帧配置与渲染资源
+     * 首帧通知版本，避免旧流回调影响新流。
      */
-    private interpolationOptions?;
-    private interpolationPipeline?;
-    private interpolationCanvas?;
+    private frameNotificationSequence;
     /**
      * 呈现统计组件
      */
     private readonly statisticsController;
+    /**
+     * 远端画面预热与渐入组件
+     */
+    private readonly warmupController;
     /**
      * DOM 挂载状态
      */
@@ -1627,17 +2097,46 @@ declare class XmaxVideoView {
      * 轨迹交互配置与懒加载视图
      */
     private interactionEnabled;
+    /**
+     * 接入方提供的轨迹视觉效果实现。
+     */
     private customTrajectoryRenderer?;
+    /**
+     * 视口触点采样与轨迹效果覆盖层。
+     */
     private trajectoryOverlay?;
     /**
      * 创建单轨视频视图。
      *
      * @param options.videoContentMode 视频内容显示模式，默认 fill。
+     * @param options.isInteractionEnabled 是否允许远端轨迹交互，默认 true。
+     * @param options.fadeInDurationMs 远端画面预热完成后的渐入时长，单位为毫秒，默认 300；0 表示直接显示，不跳过预热。
+     * @throws 渐入时长为负数或非有限数值时抛出 invalidConfiguration。
      */
     constructor(options?: {
         videoContentMode?: VideoContentMode;
         isInteractionEnabled?: boolean;
+        /**
+         * 远端画面的渐入时长，单位为毫秒，默认 300；0 表示预热完成后直接显示。
+         */
+        fadeInDurationMs?: number;
     });
+    /**
+     * 远端画面预热完成后的渐入时长，单位为毫秒。
+     */
+    get fadeInDurationMs(): number;
+    /**
+     * 更新下一次渐入时长，0 表示直接显示，不跳过渲染预热。
+     */
+    set fadeInDurationMs(durationMs: number);
+    /**
+     * 是否显示视频画面，默认 true；隐藏时保留播放、解码和触控轨迹。
+     */
+    get isVideoVisible(): boolean;
+    /**
+     * 即时切换视频的显隐，不改变触控配置或媒体流。
+     */
+    set isVideoVisible(visible: boolean);
     /**
      * 是否允许远端轨迹交互；本地轨道没有交互绑定，不受此开关影响。
      */
@@ -1675,7 +2174,7 @@ declare class XmaxVideoView {
      */
     get videoContentMode(): VideoContentMode;
     /**
-     * 更新视频及插帧画布的内容缩放方式；相同配置不重复应用。
+     * 更新视频的内容缩放方式；相同配置不重复应用。
      */
     set videoContentMode(mode: VideoContentMode);
     /**
@@ -1694,26 +2193,14 @@ declare class XmaxVideoView {
      * 从容器元素移除。
      */
     detach(): void;
-    /**
-     * 设置网络视频预览；静音播放一次，不捕获或发布媒体轨道。 @internal
-     */
-    setVideoURL(url: string | null): void;
     /**
      * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
      */
     setMediaStream(stream: MediaStream | null): void;
     /**
-     * 由远端绑定注入配置；本地预览不走此管线。 @internal
-     */
-    setFrameInterpolation(options?: RemoteFrameInterpolationOptions): void;
-    /**
-     * 视图已挂载且媒体与配置就绪时创建插帧画布和管线，避免重复启动。
+     * 新生成任务重新等待首帧和预热，不替换正在播放的媒体流。 @internal
      */
-    private startInterpolation;
-    /**
-     * 停止并释放插帧管线，移除辅助画布，保留原始视频元素。
-     */
-    private stopInterpolation;
+    prepareForGeneration(): void;
     /**
      * 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。
      */
@@ -1730,6 +2217,10 @@ declare class XmaxVideoView {
      * 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。
      */
     private cancelFrameDisplayNotification;
+    /**
+     * 仅远端渲染绑定启用预热，本地预览和普通媒体直接显示。
+     */
+    private prepareRenderWarmup;
     /**
      * 应用显示模式与镜像样式。
      */
@@ -1749,15 +2240,12 @@ declare class XmaxVideoView {
 }
 
 /**
- * 在本地预览和远端生成画面之间自动切换的视频容器（框架无关）。
+ * 双轨视频容器：在本地预览和远端生成画面之间自动切换（框架无关）。
  *
- * 设置远端轨道后，容器等待首帧实际提交显示再渐入远端画面；
+ * 设置 SDK 远端轨道后，等待首帧及渲染预热结束再渐入远端画面；
  * 远端轨道置空时立即恢复本地预览。
  */
-declare class XmaxRealtimeVideoView {
-    /**
-     * 视图元素
-     */
+declare class XmaxRealtimeDualVideoView {
     /**
      * 视图根元素。
      */
@@ -1766,26 +2254,49 @@ declare class XmaxRealtimeVideoView {
      * 视频视图
      */
     private readonly localVideoView;
+    /**
+     * 展示生成结果流的远端视频视图。
+     */
     private readonly remoteVideoView;
     /**
      * 公共配置
      */
     private currentLocalTrack?;
+    /**
+     * 当前绑定的远端视频轨。
+     */
     private currentRemoteTrack?;
+    /**
+     * 画面在视口中的缩放与裁剪方式。
+     */
     private contentMode;
+    /**
+     * 远端画面渐入时长，单位为秒。
+     */
+    private fadeInDuration;
     /**
      * 创建实时视频容器。
      *
      * @param options.localTrack 需要持续预览的本地视频轨道。
      * @param options.remoteTrack 需要覆盖显示的远端生成视频轨道。
      * @param options.videoContentMode 本地与远端视频的内容显示模式，默认 fill。
+     * @param options.remoteVideoFadeInDuration 远端渐入时长，单位为秒，默认 0.3；非正数或非有限值关闭动画。
      */
     constructor(options?: {
         localTrack?: RealtimeVideoTrack;
         remoteTrack?: RealtimeVideoTrack;
         videoContentMode?: VideoContentMode;
+        remoteVideoFadeInDuration?: number;
         isInteractionEnabled?: boolean;
     });
+    /**
+     * 远端画面的渐入时长，单位为秒，默认 0.3。
+     */
+    get remoteVideoFadeInDuration(): number;
+    /**
+     * 配置下一次渐入；非正数或非有限值关闭动画，不跳过首帧等待及渲染预热。
+     */
+    set remoteVideoFadeInDuration(duration: number);
     /**
      * 当前显示的本地视频轨道。
      */
@@ -1812,7 +2323,7 @@ declare class XmaxRealtimeVideoView {
     set localTrack(track: RealtimeVideoTrack | undefined);
     /**
      * 当前显示的远端生成视频轨道。
-     * 设置新轨道后等待首帧提交显示再渐入；置空时立即恢复本地预览。
+     * SDK 远端轨道等待首帧及预热后渐入；置空时立即恢复本地预览。
      */
     get remoteTrack(): RealtimeVideoTrack | undefined;
     /**
@@ -1844,7 +2355,7 @@ declare class XmaxRealtimeVideoView {
      */
     detach(): void;
     /**
-     * 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。
+     * 更新远端轨道绑定；SDK 轨道共用单轨视图的预热，普通轨道等待首帧后渐入。
      */
     private updateRemoteTrack;
     /**
@@ -1853,4 +2364,90 @@ declare class XmaxRealtimeVideoView {
     private showRemoteVideo;
 }
 
-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 };
+/**
+ * 绿色发光尾迹与触点装饰；仅负责绘制，不参与采样或信令发送。
+ */
+declare class DefaultTrajectoryEffectRenderer implements TrajectoryEffectRendering {
+    /**
+     * 画布与动画资源；尾迹保留像素渐隐，触点装饰每帧重绘。
+     */
+    readonly element: HTMLDivElement;
+    /**
+     * 绘制轨迹线条的画布。
+     */
+    private readonly trailCanvas;
+    /**
+     * 绘制触点光圈的画布。
+     */
+    private readonly effectCanvas;
+    /**
+     * 下一次动画刷新任务的句柄。
+     */
+    private animation?;
+    /**
+     * 轨迹画布中是否仍有待淡出的像素。
+     */
+    private hasTrailPixels;
+    /**
+     * 无活动触点后已经执行的淡出帧数。
+     */
+    private idleFadeFrames;
+    /**
+     * 活动触点和等待下一帧绘制的线段。
+     */
+    private readonly pointers;
+    /**
+     * 等待绘制的轨迹线段。
+     */
+    private readonly segments;
+    /**
+     * 安装独立视觉图层，不注册指针事件。
+     */
+    constructor();
+    /**
+     * 开始触点装饰，脉冲动画以本次按下时间为起点。
+     */
+    renderBegan(points: readonly TrajectoryPoint[]): void;
+    /**
+     * 只绘制新线段，旧像素自然衰减，不反复加亮整条历史轨迹。
+     */
+    renderMoved(points: readonly TrajectoryPoint[]): void;
+    /**
+     * 释放触点后移除装饰，仅保留尾迹的渐隐动画。
+     */
+    renderEnded(identifiers: readonly TrajectoryID[]): void;
+    /**
+     * 清除画面、待绘制数据及动画，允许同一 Renderer 再次挂载。
+     */
+    reset(): void;
+    /**
+     * 仅在触点、待绘制线段或残留尾迹存在时申请下一帧。
+     */
+    private schedule;
+    /**
+     * 同步画布分辨率，分别更新尾迹和触点视觉图层。
+     */
+    private draw;
+    /**
+     * 叠加绿色外晕、中层和白色线芯；多指时省略阴影降低绘制开销。
+     */
+    private drawSegments;
+    /**
+     * 绘制触点周围两层不同相位的脉冲圆环。
+     */
+    private drawRings;
+    /**
+     * 绘制四个反向交错运动的柔和环绕粒子。
+     */
+    private drawParticles;
+    /**
+     * 绘制径向绿色光晕，触点核心增加中间色阶。
+     */
+    private drawGlow;
+    /**
+     * 统一轨迹主题色，透明度由各视觉层指定。
+     */
+    private green;
+}
+
+export { CameraPosition, type CameraRotation, DefaultTrajectoryEffectRenderer, type DownlinkVideoStatistics, type DownlinkVideoStatisticsListener, type JsonValue, MediaService, type MediaServicing, NonRealtimeQuality, type NonRealtimeResult, type NonRealtimeTask, NonRealtimeTaskError, type NonRealtimeTaskListOptions, type NonRealtimeTaskOptions, type NonRealtimeTaskPage, NonRealtimeTaskStatus, type NonRealtimeWaitOptions, type RealtimeAudioFrame, RealtimeCameraPreset, RealtimeConfiguration, RealtimeConnectionState, RealtimeContext, type RealtimeContextInit, type RealtimeExternalAudioFrame, type RealtimeExternalFrameSink, type RealtimeExternalVideoSource, type RealtimeExternalVideoStreamOptions, type RealtimeExtraParams, type RealtimeMediaFrame, type RealtimeMediaFrameListener, RealtimeMediaStream, RealtimeModel, type RealtimeModelName, type RealtimeNetworkQuality, RealtimeNetworkQualityLevel, type RealtimeNetworkQualityListener, RealtimeQualityLevel, RealtimeReason, RealtimeState, type RealtimeStateListener, type RealtimeTiming, type RealtimeTimingListener, RealtimeVideoFormat, type RealtimeVideoFrame, RealtimeVideoTrack, type RemoteMediaTracks, RtcProvider, StorageService, type StorageServicing, type StorageUploadOptions, StoredFile, TrajectoryEffectRendering, TrajectoryID, TrajectoryPoint, type UplinkVideoStatistics, type UplinkVideoStatisticsListener, VideoContentMode, VideoRenderStatistics, XmaxClient, XmaxConfiguration, type XmaxConfigurationInit, XmaxEnvironment, XmaxError, XmaxErrorCode, type XmaxErrorListener, XmaxLogger, XmaxLoggerOption, type XmaxNonRealtimeManaging, XmaxRealtimeDualVideoView, type XmaxRealtimeManaging, XmaxRealtimeVideoView, apiBaseURL, cameraPresetSize, defaultCameraVideoFormat, defaultFrameRate, modelDisplayName, realtimeApiBaseURL, supportedRtcProviders, supportedVideoFormats };