@xmaxai/web-sdk 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -1,28 +1,47 @@
-import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode } from './VideoContentMode-BXkqM4XG.cjs';
-export { b as RealtimeVideoEncoderPreference, c as RealtimeVideoFormatInit } from './VideoContentMode-BXkqM4XG.cjs';
+import { R as RealtimeVideoFormat, a as RealtimeVideoTrack, C as CameraPosition, V as VideoContentMode } from './VideoContentMode-BM97_H8V.cjs';
+export { b as RealtimeVideoEncoderPreference, c as RealtimeVideoFormatInit } from './VideoContentMode-BM97_H8V.cjs';
 
 /**
  * SDK 当前支持的实时生成模型。
  */
 declare enum RealtimeModel {
-    /** Xmax X2 Fast 1080P 实时生成模型。 */
+    /**
+     * Xmax X2.0 实时生成模型。
+     */
+    x2_0 = "x2.0",
+    /**
+     * Xmax X2.0 Pro 实时生成模型。
+     */
+    x2_0_pro = "x2.0-pro",
+    /**
+     * Xmax X2 Fast 1080P 实时生成模型。
+     */
     x2_fast_1080p = "x2-fast-1080p"
 }
 interface ModelSize {
     width: number;
     height: number;
 }
-/** 未指定视频规格时，各媒体来源使用的默认帧率。 */
+/**
+ * 未指定视频规格时，各媒体来源使用的默认帧率。
+ */
 declare function defaultFrameRate(_model: RealtimeModel): number;
-/** 摄像头采集使用的默认视频规格。 */
-declare function defaultCameraVideoFormat(_model: RealtimeModel): RealtimeVideoFormat;
+/**
+ * 摄像头采集使用的默认视频规格。
+ */
+declare function defaultCameraVideoFormat(model: RealtimeModel): RealtimeVideoFormat;
 
 /**
  * 定义媒体输入规则与平台媒体能力查询能力。
  */
 interface MediaServicing {
-    /** 校验并保留原始尺寸；Web 插帧不降低回传分辨率。 */
+    /**
+     * 校验并保留原始尺寸；Web 插帧不降低回传分辨率。
+     */
     resolveFrameInterpolationSize(size: ModelSize): ModelSize;
+    /**
+     * 异步判断平台是否支持指定尺寸的插帧；不代表运行期性能保证。
+     */
     supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
     /**
      * 按模型输入规则解析目标尺寸。
@@ -39,11 +58,20 @@ interface MediaServicing {
  * 上传完成后返回的已存储文件信息。
  */
 declare class StoredFile {
-    /** 文件的访问地址。 */
+    /**
+     * 存储结果
+     */
+    /**
+     * 文件的访问地址。
+     */
     readonly url: string;
-    /** 对象存储中的对象键。 */
+    /**
+     * 对象存储中的对象键。
+     */
     readonly objectKey: string;
-    /** 对象存储返回的 ETag；未返回时为空。 */
+    /**
+     * 对象存储返回的 ETag；未返回时为空。
+     */
     readonly etag?: string;
     /**
      * 创建已存储文件信息。
@@ -59,15 +87,25 @@ declare class StoredFile {
     });
 }
 
-/** 上传图片的参数。 */
+/**
+ * 上传图片的参数。
+ */
 interface StorageUploadOptions {
-    /** 图片数据。 */
+    /**
+     * 图片数据。
+     */
     data: Blob | ArrayBuffer | Uint8Array;
-    /** 文件名；用于对象键后缀和缺省内容类型推断。 */
+    /**
+     * 文件名；用于对象键后缀和缺省内容类型推断。
+     */
     fileName: string;
-    /** 图片 MIME 类型；缺省按文件名后缀推断。 */
+    /**
+     * 图片 MIME 类型；缺省按文件名后缀推断。
+     */
     contentType?: string;
-    /** 上传进度回调（已传字节数、总字节数）。 */
+    /**
+     * 上传进度回调（已传字节数、总字节数）。
+     */
     onProgress?: (transferred: number, total: number) => void;
 }
 /**
@@ -86,70 +124,121 @@ interface StorageServicing {
     uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
 }
 
+/**
+ * 远端视频插帧的开关与显示帧率配置。
+ */
 interface FrameInterpolationConfiguration {
-    /** 是否请求开启远端插帧，默认 true。不支持时自动播放原视频。 */
+    /**
+     * 是否请求开启远端插帧，默认 false。不支持时自动播放原视频。
+     */
     enabled?: boolean;
-    /** 显示帧率上限，默认 60；每对源帧最多插入一帧。取值 1–60。 */
+    /**
+     * 显示帧率上限，默认 60；每对源帧最多插入一帧。取值 1–60。
+     */
     targetFrameRate?: number;
 }
 interface RealtimeConfigurationInit {
-    /** 实时生成业务使用的模型。 */
+    /**
+     * 实时生成业务使用的模型。
+     */
     model: RealtimeModel;
     /**
-     * 是否默认开启远端生成画面的插帧。
+     * 是否默认开启远端生成画面的插帧，默认 false。
      * frameInterpolation.enabled 显式设置时优先。
      */
     isFrameInterpolationEnabled?: boolean;
+    /**
+     * 插帧详细配置；enabled 显式设置时优先于简化开关。
+     */
     frameInterpolation?: FrameInterpolationConfiguration;
 }
 /**
  * 创建实时 Manager 所需的业务配置。
  */
 declare class RealtimeConfiguration {
-    /** 实时生成业务使用的模型。 */
+    /**
+     * 模型配置
+     */
+    /**
+     * 实时生成业务使用的模型。
+     */
     readonly model: RealtimeModel;
-    /** 是否默认请求开启远端生成画面的插帧。 */
+    /**
+     * 远端插帧配置
+     */
+    /**
+     * 是否默认请求开启远端生成画面的插帧。
+     */
     readonly isFrameInterpolationEnabled: boolean;
+    /**
+     * 已补全默认值的只读插帧配置。
+     */
     readonly frameInterpolation: Readonly<Required<FrameInterpolationConfiguration>>;
     /**
      * 创建实时业务配置。
      *
      * @param init.model 实时生成业务使用的模型。
      * @param init.isFrameInterpolationEnabled 是否默认开启远端生成画面的插帧。
+     * @param init.frameInterpolation 插帧开关和显示帧率上限的详细配置。
      */
     constructor(init: RealtimeConfigurationInit);
 }
 
-/** TRTC 网络质量等级：未知、极好、良好、一般、差、极差、断网。 */
+/**
+ * TRTC 网络质量等级：未知、极好、良好、一般、差、极差、断网。
+ */
 type NetworkQualityLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6;
-/** 本端 RTC 连接的网络统计，不依赖远端生成流是否已经到达。 */
+/**
+ * 本端 RTC 连接的网络统计，不依赖远端生成流是否已经到达。
+ */
 interface NetworkStatistics {
     readonly uplinkQuality?: NetworkQualityLevel;
-    /** 所有下行连接的平均网络质量。 */
+    /**
+     * 所有下行连接的平均网络质量。
+     */
     readonly downlinkQuality?: NetworkQualityLevel;
-    /** 上行连接到 TRTC 云端的往返延迟，单位 ms，不是单程延迟。 */
+    /**
+     * 上行连接到 TRTC 云端的往返延迟，单位 ms，不是单程延迟。
+     */
     readonly uplinkRttMs?: number;
-    /** 所有下行连接到 TRTC 云端的平均往返延迟，单位 ms。 */
+    /**
+     * 所有下行连接到 TRTC 云端的平均往返延迟，单位 ms。
+     */
     readonly downlinkRttMs?: number;
 }
-/** undefined 表示尚无采样或连接已清理。 */
+/**
+ * undefined 表示尚无采样或连接已清理。
+ */
 type NetworkStatisticsListener = (statistics: NetworkStatistics | undefined) => void;
 
 interface RealtimeContextInit {
-    /** 实时生成使用的文本条件。 */
+    /**
+     * 实时生成使用的文本条件。
+     */
     prompt: string;
-    /** 已上传参考图片的可选远端路径。 */
+    /**
+     * 已上传参考图片的可选远端路径。
+     */
     referencePath?: string;
 }
 /**
  * 单次实时生成任务的文本和参考资源上下文。
  */
 declare class RealtimeContext {
-    /** 实时生成使用的文本条件。 */
+    /**
+     * 生成条件
+     */
+    /**
+     * 实时生成使用的文本条件。
+     */
     readonly prompt: string;
-    /** 已上传参考图片的可选远端路径。 */
+    /**
+     * 已上传参考图片的可选远端路径。
+     */
     readonly referencePath?: string;
-    /** 创建实时生成条件并规范化文本和参考路径。 */
+    /**
+     * 创建实时生成条件并规范化文本和参考路径。
+     */
     constructor(init: RealtimeContextInit);
 }
 
@@ -157,9 +246,16 @@ declare class RealtimeContext {
  * 实时生成输入/输出的媒体流。
  */
 declare class RealtimeMediaStream {
-    /** 媒体流标识。 */
+    /**
+     * 流标识与轨道
+     */
+    /**
+     * 媒体流标识。
+     */
     readonly id: string;
-    /** 媒体流包含的视频轨道。 */
+    /**
+     * 媒体流包含的视频轨道。
+     */
     readonly videoTrack?: RealtimeVideoTrack;
     /**
      * 创建实时媒体流。
@@ -177,52 +273,97 @@ declare class RealtimeMediaStream {
  * SDK 向接入方暴露的统一错误码。
  */
 declare enum XmaxErrorCode {
-    /** API Key 未配置或为空。 */
+    /**
+     * API Key 未配置或为空。
+     */
     invalidAPIKey = "INVALID_API_KEY",
-    /** 调用参数、配置或当前生命周期状态不符合操作要求。 */
+    /**
+     * 调用参数、配置或当前生命周期状态不符合操作要求。
+     */
     invalidConfiguration = "INVALID_CONFIGURATION",
-    /** SDK 内部发生无法归类的非预期错误。 */
+    /**
+     * SDK 内部发生无法归类的非预期错误。
+     */
     internalError = "INTERNAL_ERROR",
-    /** 网络不可用、连接失败或 HTTP 请求无法完成。 */
+    /**
+     * 网络不可用、连接失败或 HTTP 请求无法完成。
+     */
     networkError = "NETWORK_ERROR",
-    /** Xmax API 返回业务失败，或者响应数据无法正确解析。 */
+    /**
+     * Xmax API 返回业务失败，或者响应数据无法正确解析。
+     */
     apiError = "API_ERROR",
-    /** 实时生成会话数据缺失、会话关闭或心跳状态异常。 */
+    /**
+     * 实时生成会话数据缺失、会话关闭或心跳状态异常。
+     */
     sessionError = "SESSION_ERROR",
-    /** RTC Engine、房间、媒体传输或渲染绑定发生错误。 */
+    /**
+     * RTC Engine、房间、媒体传输或渲染绑定发生错误。
+     */
     rtcError = "RTC_ERROR",
-    /** 本地媒体读取、解码、同步或帧处理发生错误。 */
+    /**
+     * 本地媒体读取、解码、同步或帧处理发生错误。
+     */
     mediaError = "MEDIA_ERROR",
-    /** 当前系统、设备或视频规格不支持远端视频插帧。 */
+    /**
+     * 当前系统、设备或视频规格不支持远端视频插帧。
+     */
     frameInterpolationUnsupported = "FRAME_INTERPOLATION_UNSUPPORTED",
-    /** 接入方未授予相机权限。 */
+    /**
+     * 接入方未授予相机权限。
+     */
     cameraPermissionDenied = "CAMERA_PERMISSION_DENIED",
-    /** 启动相机在限定时间内未获得足够明亮且稳定的画面，未发布视频。 */
+    /**
+     * @deprecated 为兼容保留；相机亮度检查超时现仅记录警告并继续流程，不再抛出此错误。
+     */
     cameraExposureTimeout = "CAMERA_EXPOSURE_TIMEOUT",
-    /** 接入方未授予麦克风权限。 */
+    /**
+     * 接入方未授予麦克风权限。
+     */
     microphonePermissionDenied = "MICROPHONE_PERMISSION_DENIED",
-    /** 文件或二进制数据上传失败。 */
+    /**
+     * 文件或二进制数据上传失败。
+     */
     uploadError = "UPLOAD_ERROR",
-    /** 远端文件下载失败。 */
+    /**
+     * 远端文件下载失败。
+     */
     downloadError = "DOWNLOAD_ERROR",
-    /** 图片未通过内容安全检查。 */
+    /**
+     * 图片未通过内容安全检查。
+     */
     unsafeImage = "UNSAFE_IMAGE",
-    /** 操作因生命周期切换或接入方主动终止而正常取消。 */
+    /**
+     * 操作因生命周期切换或接入方主动终止而正常取消。
+     */
     cancelled = "CANCELLED",
-    /** 等待连接、房间事件或生成结果超过规定时间。 */
+    /**
+     * 等待连接、房间事件或生成结果超过规定时间。
+     */
     timeout = "TIMEOUT"
 }
-/** SDK 内部组件上报统一错误时使用的监听器。 */
+/**
+ * SDK 内部组件上报统一错误时使用的监听器。
+ */
 type XmaxErrorListener = (error: XmaxError) => void;
 /**
  * 表示 SDK 抛出或回调给接入方的统一错误。
  */
 declare class XmaxError extends Error {
-    /** SDK 统一错误码。 */
+    /**
+     * 错误信息
+     */
+    /**
+     * SDK 统一错误码。
+     */
     readonly code: XmaxErrorCode;
-    /** Xmax API 返回的业务错误码；非 API 业务错误时为空。 */
+    /**
+     * Xmax API 返回的业务错误码；非 API 业务错误时为空。
+     */
     readonly apiCode?: number;
-    /** HTTP 响应状态码；请求未获得响应时为空。 */
+    /**
+     * HTTP 响应状态码；请求未获得响应时为空。
+     */
     readonly httpStatus?: number;
     /**
      * 创建 SDK 错误。
@@ -248,19 +389,33 @@ declare class XmaxError extends Error {
  * 实时业务连接状态。
  */
 declare enum RealtimeConnectionState {
-    /** 没有可用的本地媒体流。 */
+    /**
+     * 没有可用的本地媒体流。
+     */
     idle = "Idle",
-    /** 正在准备本地媒体流；摄像头还需等待有效帧和预览视图绑定。 */
+    /**
+     * 正在准备本地媒体流；摄像头还需等待有效帧和预览视图绑定。
+     */
     preparing = "Preparing",
-    /** 本地媒体流已就绪，可以预览、连接和生成。 */
+    /**
+     * 本地媒体流已就绪，可以预览、连接和生成。
+     */
     ready = "Ready",
-    /** 正在创建 Session、加入 Room 并发布本地流。 */
+    /**
+     * 正在创建 Session、加入 Room 并发布本地流。
+     */
     connecting = "Connecting",
-    /** 实时连接已建立，当前没有生成任务。 */
+    /**
+     * 实时连接已建立，当前没有生成任务。
+     */
     connected = "Connected",
-    /** 实时连接已建立且生成任务正在运行。 */
+    /**
+     * 实时连接已建立且生成任务正在运行。
+     */
     generating = "Generating",
-    /** 正在清理生成、Room 和 Session 资源。 */
+    /**
+     * 正在清理生成、Room 和 Session 资源。
+     */
     disconnecting = "Disconnecting"
 }
 /**
@@ -277,6 +432,9 @@ type RealtimeReason = {
 declare const RealtimeReason: {
     normal: RealtimeReason;
     orientationChanged: RealtimeReason;
+    /**
+     * 将 SDK 错误包装为状态切换原因，保留错误码和原始说明。
+     */
     failure(error: XmaxError): RealtimeReason;
 };
 interface RealtimeStateInit {
@@ -289,13 +447,30 @@ interface RealtimeStateInit {
  * 实时业务当前状态快照。
  */
 declare class RealtimeState {
-    /** 当前连接生命周期状态。 */
+    /**
+     * 连接生命周期
+     */
+    /**
+     * 当前连接生命周期状态。
+     */
     readonly connectionState: RealtimeConnectionState;
-    /** 当前或最近一次实时 Session 标识。 */
+    /**
+     * 业务标识
+     */
+    /**
+     * 当前或最近一次实时 Session 标识。
+     */
     readonly sessionID?: string;
-    /** 当前生成任务标识。 */
+    /**
+     * 当前生成任务标识。
+     */
     readonly taskID?: string;
-    /** 进入当前状态的原因；正常开始新的操作时清空。 */
+    /**
+     * 状态变化原因
+     */
+    /**
+     * 进入当前状态的原因；正常开始新的操作时清空。
+     */
     readonly reason?: RealtimeReason;
     /**
      * 创建实时状态快照。
@@ -313,70 +488,120 @@ declare class RealtimeState {
      */
     equals(other: RealtimeState): boolean;
 }
-/** 实时状态监听器。 */
+/**
+ * 实时状态监听器。
+ */
 type RealtimeStateListener = (state: RealtimeState) => void;
 
 /**
- * 一次相机启动的耗时快照，单位为毫秒；undefined 表示该阶段尚未完成。
+ * 一次相机启动的耗时快照，单位为毫秒；undefined 表示该阶段尚未完成或未启用。
  * 新一轮打开摄像头时重置；失败、关闭或断开后保留已完成的值。
  * 仅预览时不产生首帧和总耗时；预览后手动启动生成的等待计入总耗时。
  */
 interface RealtimeLaunchTiming {
-    /** 开始打开摄像头到相机流创建完成（包含权限等待）。 */
+    /**
+     * 开始打开摄像头到相机流创建完成（包含权限等待）。
+     */
     readonly cameraMs?: number;
-    /** 开始创建会话到 RTC 进房并发布本地流完成。 */
+    /**
+     * 开始创建会话到 RTC 进房配置完成；不含等待亮度检测及发布本地流。
+     */
     readonly connectionMs?: number;
-    /** 开始发送生成信令到 SDK 远端视图首次呈现视频帧。 */
+    /**
+     * 相机亮度检测开始到首张合格帧或超时放行；与建立连接并行，不可直接相加。禁用检测时为 undefined。
+     */
+    readonly frameValidationMs?: number;
+    /**
+     * 开始发送生成信令到 SDK 远端视图首次呈现视频帧。
+     */
     readonly firstFrameMs?: number;
-    /** 开始打开摄像头到 SDK 远端视图首次呈现视频帧。 */
+    /**
+     * 开始打开摄像头到 SDK 远端视图首次呈现视频帧的实际总耗时，并非各项之和。
+     */
     readonly totalMs?: number;
 }
-/** 阶段完成时提供完整快照；不支持帧回调的浏览器以 playing 近似首帧。 */
+/**
+ * 阶段完成时提供完整快照；不支持帧回调的浏览器以 playing 近似首帧。
+ */
 type RealtimeLaunchTimingListener = (timing: RealtimeLaunchTiming) => void;
 
-/** 视频流实际运行统计；缺失或无效指标为 undefined。 */
+/**
+ * 视频流实际运行统计；缺失或无效指标为 undefined。
+ */
 interface VideoStatistics {
     readonly width?: number;
     readonly height?: number;
-    /** 实际帧率，单位 fps。 */
+    /**
+     * 实际帧率，单位 fps。
+     */
     readonly frameRate?: number;
-    /** 实际码率，单位 kbps。 */
+    /**
+     * 实际码率，单位 kbps。
+     */
     readonly bitrateKbps?: number;
 }
-/** undefined 表示当前没有可用统计（尚未发布、断开或停止）。 */
+/**
+ * undefined 表示当前没有可用统计（尚未发布、断开或停止）。
+ */
 type VideoStatisticsListener = (statistics: VideoStatistics | undefined) => void;
-/** 一路远端主视频流的接收统计。 */
+/**
+ * 一路远端主视频流的接收统计。
+ */
 interface RemoteVideoStatistics extends VideoStatistics {
     readonly userID: string;
-    /** 本端 SDK 到 TRTC 云端的往返延迟，单位 ms；不是与远端用户之间的 RTT。 */
+    /**
+     * 本端 SDK 到 TRTC 云端的往返延迟，单位 ms；不是与远端用户之间的 RTT。
+     */
     readonly rttMs?: number;
-    /** 本端 SDK 到 TRTC 云端的上行丢包率，单位 %，不是结果流的发送端丢包率。 */
+    /**
+     * 本端 SDK 到 TRTC 云端的上行丢包率，单位 %，不是结果流的发送端丢包率。
+     */
     readonly uplinkLossPercent?: number;
-    /** TRTC 云端到本端 SDK 的下行丢包率，单位 %。 */
+    /**
+     * TRTC 云端到本端 SDK 的下行丢包率，单位 %。
+     */
     readonly downlinkLossPercent?: number;
-    /** 当前远端视频流的播放缓冲延迟，单位 ms。 */
+    /**
+     * 当前远端视频流的播放缓冲延迟，单位 ms。
+     */
     readonly jitterBufferDelayMs?: number;
-    /** TRTC 媒体端到端延迟估算值，单位 ms；不代表完整 AI 处理链路耗时。 */
+    /**
+     * TRTC 媒体端到端延迟估算值，单位 ms；不代表完整 AI 处理链路耗时。
+     */
     readonly endToEndDelayMs?: number;
 }
-/** undefined 表示当前结果流没有统计或已被清理。 */
+/**
+ * undefined 表示当前结果流没有统计或已被清理。
+ */
 type RemoteVideoStatisticsListener = (statistics: RemoteVideoStatistics | undefined) => void;
 
 /**
  * 定义 SDK 对接入方提供的实时媒体与生成控制能力。
  */
 interface XmaxRealtimeManaging {
-    /** 实时能力配置。 */
+    /**
+     * 实时能力配置。
+     */
     readonly options: RealtimeConfiguration;
-    /** 当前实时连接与生成状态。 */
+    /**
+     * 当前实时连接与生成状态。
+     */
     readonly currentState: RealtimeState;
-    /** 插帧功能开关；不随首帧等待、跳帧或视图挂载变化，不支持或故障降级时关闭。 */
+    /**
+     * 插帧功能开关；不随首帧等待、跳帧或视图挂载变化，不支持或故障降级时关闭。
+     */
     readonly isFrameInterpolationEnabled: boolean;
-    /** 切换客户端插帧，不改变回传分辨率或重启任务。不支持时抛错且保留配置。 */
+    /**
+     * 切换客户端插帧，不改变回传分辨率或重启任务。不支持时抛错且保留配置。
+     */
     setFrameInterpolationEnabled(enabled: boolean): Promise<void>;
-    /** 当前本地媒体预览音量，取值范围为 `0...1`。 */
+    /**
+     * 当前本地媒体预览音量，取值范围为 `0...1`。
+     */
     readonly localAudioVolume: number;
-    /** 当前远端生成音频播放音量，取值范围为 `0...1`。 */
+    /**
+     * 当前远端生成音频播放音量，取值范围为 `0...1`。
+     */
     readonly remoteAudioVolume: number;
     /**
      * 设置实时状态监听器。
@@ -430,8 +655,14 @@ interface XmaxRealtimeManaging {
         videoFormat: RealtimeVideoFormat;
         position: CameraPosition;
         useMicrophone: boolean;
+        /**
+         * 是否在发布前检测相机帧亮度，默认 true；false 跳过检测及其等待，不产生检测耗时。
+         */
+        enableFrameValidation?: boolean;
     }): Promise<RealtimeMediaStream>;
-    /** 停止本地相机流并释放本地预览与 RTC 资源。 */
+    /**
+     * 停止本地相机流并释放本地预览与 RTC 资源。
+     */
     stopLocalCameraStream(): Promise<void>;
     /**
      * 切换前后置摄像头。
@@ -446,8 +677,8 @@ interface XmaxRealtimeManaging {
      * 使用当前 Manager 创建的本地流建立实时连接。
      *
      * 创建实时会话、加入 RTC 房间并发布本地流，成功后启动会话心跳。
-     * 发布前并行检查相机亮度稳定性；5 秒内未通过检查时抛出
-     * `cameraExposureTimeout`，不发布媒体，接入方可改善光照后重试。
+     * 启用帧检测时，发布前并行检查相机亮度，首张合格帧即放行；2 秒内未通过检查则
+     * 记录警告并按当前画面继续发布，不因环境较暗而阻断连接。
      * 返回的远端媒体流在生成开始后承载远端生成画面。
      *
      * @param localStream 由 `createLocalCameraStream` 创建的本地媒体流。
@@ -456,7 +687,9 @@ interface XmaxRealtimeManaging {
      * 发布失败时抛出错误；失败时自动释放连接资源并恢复本地预览。
      */
     connect(localStream: RealtimeMediaStream): Promise<RealtimeMediaStream>;
-    /** 断开实时连接并保留当前本地媒体预览。 */
+    /**
+     * 断开实时连接并保留当前本地媒体预览。
+     */
     disconnect(): Promise<void>;
     /**
      * 关闭当前实时生命周期并释放连接、本地媒体和 RTC Engine。
@@ -485,12 +718,18 @@ interface XmaxRealtimeManaging {
  * Xmax 服务环境。
  */
 declare enum XmaxEnvironment {
-    /** 国内环境。 */
+    /**
+     * 国内环境。
+     */
     china = "china",
-    /** 海外环境。 */
+    /**
+     * 海外环境。
+     */
     global = "global"
 }
-/** 环境对应的 Xmax API Base URL。 */
+/**
+ * 环境对应的 Xmax API Base URL。
+ */
 declare function apiBaseURL(environment: XmaxEnvironment): string;
 
 /**
@@ -498,11 +737,17 @@ declare function apiBaseURL(environment: XmaxEnvironment): string;
  */
 declare enum XmaxLoggerOption {
     none = 0,
-    /** Room、API、Realtime、Storage 等业务运行日志。 */
+    /**
+     * Room、API、Realtime、Storage 等业务运行日志。
+     */
     business = 1,
-    /** RTC 网络质量和音视频运行统计，输出到 console.info。 */
+    /**
+     * RTC 网络质量和音视频运行统计，输出到 console.info。
+     */
     performance = 2,
-    /** 输出全部 XmaxSDK 日志。 */
+    /**
+     * 输出全部 XmaxSDK 日志。
+     */
     all = 3
 }
 /**
@@ -511,6 +756,9 @@ declare enum XmaxLoggerOption {
  * 调用方不得传入 API Key、Token、Secret、Authorization 或完整敏感响应。
  */
 declare class XmaxLogger {
+    /**
+     * 分类日志
+     */
     static readonly realtime: XmaxLogger;
     static readonly rtc: XmaxLogger;
     static readonly media: XmaxLogger;
@@ -521,7 +769,13 @@ declare class XmaxLogger {
     static readonly render: XmaxLogger;
     static readonly interaction: XmaxLogger;
     static readonly permission: XmaxLogger;
+    /**
+     * 日志类别
+     */
     private readonly category;
+    /**
+     * 创建固定业务分类的日志入口，共享全局日志选项和语言配置。
+     */
     private constructor();
     /**
      * 更新 SDK 全局日志选项和细项语言，后一次配置覆盖前一次。
@@ -530,39 +784,71 @@ declare class XmaxLogger {
      * @param environment 服务环境，决定日志细项语言（国内中文，海外英文）。
      */
     static configure(options: XmaxLoggerOption, environment?: XmaxEnvironment): void;
-    /** 选择日志细项文案；日志标题保持原有中英双语。 */
+    /**
+     * 选择日志细项文案；日志标题保持原有中英双语。
+     */
     static localized(chinese: string, english: string): string;
-    /** 判断指定日志类型是否已开启。 */
+    /**
+     * 判断指定日志类型是否已开启。
+     */
     static isEnabled(option: XmaxLoggerOption): boolean;
-    /** 输出调试日志。 */
+    /**
+     * 输出调试日志。
+     */
     debug(message: () => string, option?: XmaxLoggerOption): void;
-    /** 输出信息日志。 */
+    /**
+     * 输出信息日志。
+     */
     info(message: () => string, option?: XmaxLoggerOption): void;
-    /** 输出警告日志。 */
+    /**
+     * 输出警告日志。
+     */
     warning(message: () => string, option?: XmaxLoggerOption): void;
-    /** 输出错误日志。 */
+    /**
+     * 输出错误日志。
+     */
     error(message: () => string, option?: XmaxLoggerOption): void;
-    /** 按日志类型开关输出到控制台；未开启时不求值日志内容。 */
+    /**
+     * 按日志类型开关输出到控制台；未开启时不求值日志内容。
+     */
     private log;
 }
 
 interface XmaxConfigurationInit {
-    /** 调用 Xmax 服务使用的 API Key。 */
+    /**
+     * 调用 Xmax 服务使用的 API Key。
+     */
     apiKey: string;
-    /** SDK 连接的服务环境；默认为国内环境。 */
+    /**
+     * SDK 连接的服务环境；默认为国内环境。
+     */
     environment?: XmaxEnvironment;
-    /** SDK 输出的日志类型；默认为不输出日志。 */
+    /**
+     * SDK 输出的日志类型；默认为不输出日志。
+     */
     loggerOptions?: XmaxLoggerOption;
 }
 /**
  * SDK 全局配置。
  */
 declare class XmaxConfiguration {
-    /** 调用 Xmax 服务使用的 API Key。 */
+    /**
+     * 服务身份与环境
+     */
+    /**
+     * 调用 Xmax 服务使用的 API Key。
+     */
     readonly apiKey: string;
-    /** SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。 */
+    /**
+     * SDK 连接的服务环境，同时决定日志细项语言：国内为中文，海外为英文。
+     */
     readonly environment: XmaxEnvironment;
-    /** SDK 输出的日志类型；默认为不输出日志。 */
+    /**
+     * 日志配置
+     */
+    /**
+     * SDK 输出的日志类型；默认为不输出日志。
+     */
     readonly loggerOptions: XmaxLoggerOption;
     /**
      * 创建 SDK 全局配置。
@@ -583,8 +869,16 @@ declare class XmaxConfiguration {
  * SDK 的统一入口，负责创建实时和媒体服务组件。
  */
 declare class XmaxClient {
-    /** 客户端使用的全局配置。 */
+    /**
+     * 客户端配置
+     */
+    /**
+     * 客户端使用的全局配置。
+     */
     readonly configuration: XmaxConfiguration;
+    /**
+     * 服务层组件
+     */
     private readonly apiService;
     /**
      * 创建 SDK 客户端。
@@ -619,6 +913,9 @@ declare class XmaxClient {
  * 模型输入尺寸与远端插帧能力。
  */
 declare class MediaService implements MediaServicing {
+    /**
+     * 模型约束
+     */
     readonly model: RealtimeModel;
     /**
      * 创建媒体服务。
@@ -626,14 +923,25 @@ declare class MediaService implements MediaServicing {
      * @param model 媒体输入规则使用的模型，默认为 `x2-fast-1080p`。
      */
     constructor(model?: RealtimeModel);
-    /** Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。 */
+    /**
+     * Web 插帧保留原始尺寸；/16 对齐由 GPU 内部补边处理，不缩小回传视频。
+     */
     resolveFrameInterpolationSize(size: ModelSize): ModelSize;
-    /** WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。 */
+    /**
+     * WebGPU 适配器探测是异步的；实际性能和运行状态由渲染管线判断。
+     */
     supportsFrameInterpolation(size: ModelSize): Promise<boolean>;
+    /**
+     * 按模型分辨率档位或像素预算解析输入尺寸，保持宽高比例并对齐；不支持的规格抛错。
+     */
     resolveModelInputSize(size: ModelSize): ModelSize;
-    /** 在对齐网格上选择满足面积限制且最接近目标的尺寸。 */
+    /**
+     * 在对齐网格上选择满足面积限制且最接近目标的尺寸。
+     */
     private boundedAlignedSize;
-    /** 校验尺寸为有限正数，并归一化为不小于 1 的整数。 */
+    /**
+     * 校验尺寸为有限正数，并归一化为不小于 1 的整数。
+     */
     private validatedSize;
 }
 
@@ -663,17 +971,27 @@ interface ApiServicing {
      * @throws 配置无效、网络失败、业务失败或响应无法解析时抛出错误。
      */
     request<T>(method: ApiMethod, path: string, body?: unknown): Promise<T>;
-    /** 发送 GET 请求。 */
+    /**
+     * 发送 GET 请求。
+     */
     get<T>(path: string): Promise<T>;
-    /** 发送 POST 请求。 */
+    /**
+     * 发送 POST 请求。
+     */
     post<T>(path: string, body?: unknown): Promise<T>;
-    /** 发送 PUT 请求。 */
+    /**
+     * 发送 PUT 请求。
+     */
     put<T>(path: string, body?: unknown): Promise<T>;
-    /** 发送 DELETE 请求。 */
+    /**
+     * 发送 DELETE 请求。
+     */
     delete<T>(path: string): Promise<T>;
 }
 
-/** 解析后的临时存储配置。 */
+/**
+ * 解析后的临时存储配置。
+ */
 interface TemporaryStorageConfiguration {
     bucket: string;
     region: string;
@@ -685,8 +1003,13 @@ interface TemporaryStorageConfiguration {
         sessionToken: string;
     };
 }
-/** 对象存储直传客户端需要的最小接口。 */
+/**
+ * 对象存储直传客户端需要的最小接口。
+ */
 interface StorageObjectClient {
+    /**
+     * 将文件直传到指定桶和对象键，通过回调报告错误或访问地址，并可上报上传进度。
+     */
     putObject(params: {
         Bucket: string;
         Region: string;
@@ -704,16 +1027,26 @@ interface StorageObjectClient {
         ETag?: string;
     }) => void): void;
 }
-/** 对象存储客户端工厂；生产实现按临时凭证创建 COS 客户端。 */
+/**
+ * 对象存储客户端工厂；生产实现按临时凭证创建 COS 客户端。
+ */
 type StorageObjectClientFactory = (configuration: TemporaryStorageConfiguration) => Promise<StorageObjectClient>;
 interface StorageServiceOptions {
-    /** Xmax API 请求组件。 */
+    /**
+     * Xmax API 请求组件。
+     */
     apiService: ApiServicing;
-    /** 对象存储客户端工厂（可替换，测试用）。 */
+    /**
+     * 对象存储客户端工厂（可替换，测试用）。
+     */
     clientFactory?: StorageObjectClientFactory;
-    /** 时间来源（可替换，测试用）。 */
+    /**
+     * 时间来源（可替换，测试用）。
+     */
     dateGenerator?: () => Date;
-    /** 标识来源（可替换，测试用）。 */
+    /**
+     * 标识来源（可替换，测试用）。
+     */
     identifierGenerator?: () => string;
 }
 /**
@@ -724,8 +1057,17 @@ interface StorageServiceOptions {
  * endpoint 或默认 COS 域名依次解析。
  */
 declare class StorageService implements StorageServicing {
+    /**
+     * 服务层组件
+     */
     private readonly apiService;
+    /**
+     * 平台资源
+     */
     private readonly clientFactory;
+    /**
+     * 标识生成
+     */
     private readonly dateGenerator;
     private readonly identifierGenerator;
     /**
@@ -737,30 +1079,50 @@ declare class StorageService implements StorageServicing {
      * @param options.identifierGenerator 标识来源（可替换，测试用）。
      */
     constructor(options: StorageServiceOptions);
-    /** 上传图片并返回访问地址。 */
+    /**
+     * 上传图片并返回访问地址。
+     */
     uploadImage(options: StorageUploadOptions): Promise<StoredFile>;
-    /** 获取临时存储配置；字段不完整时抛出 API 错误。 */
+    /**
+     * 获取临时存储配置；字段不完整时抛出 API 错误。
+     */
     private fetchStorageConfiguration;
-    /** 生成对象键：`${prefix}${毫秒时间戳}_${标识}_${文件名}`。 */
+    /**
+     * 生成对象键：`${prefix}${毫秒时间戳}_${标识}_${文件名}`。
+     */
     private makeObjectKey;
-    /** 生产环境 COS 客户端工厂：动态加载 cos-js-sdk-v5 并按临时凭证创建客户端。 */
+    /**
+     * 生产环境 COS 客户端工厂：动态加载 cos-js-sdk-v5 并按临时凭证创建客户端。
+     */
     private static cosClientFactory;
-    /** 调用对象存储上传并包装为 Promise。 */
+    /**
+     * 调用对象存储上传并包装为 Promise。
+     */
     private static putObject;
     /**
      * 解析对象访问地址：优先使用上传返回的 `Location`（补全协议），
      * 其次拼接自定义 endpoint，最后回退到默认 COS 域名。
      */
     private static resolveObjectURL;
-    /** 统一构造上传体。 */
+    /**
+     * 统一构造上传体。
+     */
     private static makeBody;
-    /** 校验文件名非空且不包含路径分隔符。 */
+    /**
+     * 校验文件名非空且不包含路径分隔符。
+     */
     private static validateFileName;
-    /** 按文件名后缀推断内容类型。 */
+    /**
+     * 按文件名后缀推断内容类型。
+     */
     private static inferContentType;
-    /** 格式化字节数用于日志输出。 */
+    /**
+     * 格式化字节数用于日志输出。
+     */
     private static formatByteCount;
-    /** 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。 */
+    /**
+     * 归一化可选字符串：去除首尾空白后为空时返回 `undefined`。
+     */
     private static nonEmpty;
 }
 
@@ -778,22 +1140,46 @@ interface RemoteFrameInterpolationOptions {
  * 轨道注册了渲染绑定时走绑定管线，否则按 `mediaStreamTrack` 直接渲染。
  */
 declare class XmaxVideoView {
-    /** 视图根元素（div，内含一个 video 元素）。 */
+    /**
+     * 视图元素
+     */
+    /**
+     * 视图根元素（div，内含一个 video 元素）。
+     */
     readonly element: HTMLDivElement;
-    /** @internal 渲染视频帧的元素，供绑定管线使用。 */
+    /**
+     * @internal 渲染视频帧的元素，供绑定管线使用。
+     */
     readonly videoElement: HTMLVideoElement;
-    /** 首帧实际提交显示时调用（一次性；换轨后重新武装）。 */
+    /**
+     * 公共配置
+     */
+    /**
+     * 首帧实际提交显示时调用（一次性；换轨后重新武装）。
+     */
     frameDisplayHandler?: () => void;
+    /**
+     * 渲染状态
+     */
     private currentTrack?;
     private contentMode;
     private mirrored;
+    /**
+     * 首帧显示通知与异步回调版本
+     */
     private hasNotifiedFrameDisplay;
     private onPlaying?;
     private videoFrameCallbackID?;
     private frameNotificationSequence;
+    /**
+     * 远端插帧配置与渲染资源
+     */
     private interpolationOptions?;
     private interpolationPipeline?;
     private interpolationCanvas?;
+    /**
+     * DOM 挂载状态
+     */
     private detached;
     /**
      * 创建单轨视频视图。
@@ -803,34 +1189,73 @@ declare class XmaxVideoView {
     constructor(options?: {
         videoContentMode?: VideoContentMode;
     });
-    /** 当前显示的视频轨道；切换时自动解绑旧轨道。 */
+    /**
+     * 当前显示的视频轨道；切换时自动解绑旧轨道。
+     */
     get track(): RealtimeVideoTrack | undefined;
+    /**
+     * 解绑旧轨道后接入新轨道，并为新内容重新启用一次性首帧通知。
+     */
     set track(track: RealtimeVideoTrack | undefined);
-    /** 视频内容在容器中的显示模式。 */
+    /**
+     * 视频内容在容器中的显示模式。
+     */
     get videoContentMode(): VideoContentMode;
+    /**
+     * 更新视频及插帧画布的内容缩放方式；相同配置不重复应用。
+     */
     set videoContentMode(mode: VideoContentMode);
-    /** 本地预览是否镜像显示（仅影响显示，不影响发布流）。 */
+    /**
+     * 本地预览是否镜像显示（仅影响显示，不影响发布流）。
+     */
     get isMirrored(): boolean;
+    /**
+     * 更新视图镜像变换，仅改变呈现方式，不改动媒体流。
+     */
     set isMirrored(mirrored: boolean);
-    /** 挂载到容器元素。 */
+    /**
+     * 挂载到容器元素。
+     */
     attach(to: HTMLElement): void;
-    /** 从容器元素移除。 */
+    /**
+     * 从容器元素移除。
+     */
     detach(): void;
-    /** 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal */
+    /**
+     * 直接设置渲染用的媒体流（绑定管线和直接渲染共用）。 @internal
+     */
     setMediaStream(stream: MediaStream | null): void;
-    /** 由远端绑定注入配置；本地预览不走此管线。 @internal */
+    /**
+     * 由远端绑定注入配置；本地预览不走此管线。 @internal
+     */
     setFrameInterpolation(options?: RemoteFrameInterpolationOptions): void;
+    /**
+     * 视图已挂载且媒体与配置就绪时创建插帧画布和管线，避免重复启动。
+     */
     private startInterpolation;
+    /**
+     * 停止并释放插帧管线，移除辅助画布，保留原始视频元素。
+     */
     private stopInterpolation;
-    /** 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。 */
+    /**
+     * 接入轨道画面：优先走注册的渲染绑定，否则按媒体轨直接渲染。
+     */
     private attachTrack;
-    /** 解绑当前轨道并清空渲染内容。 */
+    /**
+     * 解绑当前轨道并清空渲染内容。
+     */
     private detachCurrentTrack;
-    /** 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。 */
+    /**
+     * 首帧提交合成器时通知；旧浏览器回退到 playing 近似判断。
+     */
     private armFrameDisplayNotification;
-    /** 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。 */
+    /**
+     * 换流、解绑或卸载时取消观察，防止迟到的首帧归入下一条流。
+     */
     private cancelFrameDisplayNotification;
-    /** 应用显示模式与镜像样式。 */
+    /**
+     * 应用显示模式与镜像样式。
+     */
     private applyContentMode;
 }
 
@@ -841,10 +1266,21 @@ declare class XmaxVideoView {
  * 远端轨道置空时立即恢复本地预览。
  */
 declare class XmaxRealtimeVideoView {
-    /** 视图根元素。 */
+    /**
+     * 视图元素
+     */
+    /**
+     * 视图根元素。
+     */
     readonly element: HTMLDivElement;
+    /**
+     * 视频视图
+     */
     private readonly localVideoView;
     private readonly remoteVideoView;
+    /**
+     * 公共配置
+     */
     private currentLocalTrack?;
     private currentRemoteTrack?;
     private contentMode;
@@ -860,28 +1296,54 @@ declare class XmaxRealtimeVideoView {
         remoteTrack?: RealtimeVideoTrack;
         videoContentMode?: VideoContentMode;
     });
-    /** 当前显示的本地视频轨道。 */
+    /**
+     * 当前显示的本地视频轨道。
+     */
     get localTrack(): RealtimeVideoTrack | undefined;
+    /**
+     * 替换本地预览轨道；轨道未变化时保留当前绑定。
+     */
     set localTrack(track: RealtimeVideoTrack | undefined);
     /**
      * 当前显示的远端生成视频轨道。
      * 设置新轨道后等待首帧提交显示再渐入；置空时立即恢复本地预览。
      */
     get remoteTrack(): RealtimeVideoTrack | undefined;
+    /**
+     * 替换远端轨道并重新等待首帧渐入；清空轨道时恢复本地预览。
+     */
     set remoteTrack(track: RealtimeVideoTrack | undefined);
-    /** 视频内容在容器中的显示模式。 */
+    /**
+     * 视频内容在容器中的显示模式。
+     */
     get videoContentMode(): VideoContentMode;
+    /**
+     * 同步调整本地与远端视频在容器中的缩放和裁剪方式。
+     */
     set videoContentMode(mode: VideoContentMode);
-    /** 本地预览是否镜像显示（前置摄像头）。 */
+    /**
+     * 本地预览是否镜像显示（前置摄像头）。
+     */
     get isLocalMirrored(): boolean;
+    /**
+     * 更新本地预览镜像；不修改采集帧或远端画面。
+     */
     set isLocalMirrored(mirrored: boolean);
-    /** 挂载到容器元素。 */
+    /**
+     * 挂载到容器元素。
+     */
     attach(to: HTMLElement): void;
-    /** 从容器元素移除。 */
+    /**
+     * 从容器元素移除。
+     */
     detach(): void;
-    /** 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。 */
+    /**
+     * 更新远端轨道绑定：重置渐入状态，等待首帧提交后再显示远端画面。
+     */
     private updateRemoteTrack;
-    /** 远端首帧已提交：渐入远端画面。 */
+    /**
+     * 远端首帧已提交：渐入远端画面。
+     */
     private showRemoteVideo;
 }