@realsee/live 0.7.3-alpha.0 → 0.7.4

package/dist/rtc/BrowserRTC.d.ts

@@ -2,10 +2,53 @@ import { Client, LocalStream } from 'trtc-js-sdk';
 import { GetVoiceSign } from '../typings/live/GetVoiceSign';
 import { RTCType } from '../typings/rtc/type';
 import { CoreRTC } from './CoreRTC';
+/**
+ * TRTC 实例接口（内部使用）
+ */
 export interface ITrtcInstance {
+    /**
+     * TRTC 客户端实例
+     */
     client: Client | null;
+    /**
+     * 本地音视频流
+     */
     stream: LocalStream | null;
 }
+/**
+ * 浏览器端 TRTC RTC 实现
+ *
+ * 基于腾讯云 TRTC SDK 实现的浏览器端 RTC 类。
+ * 适用于在浏览器环境中进行实时语音通信。
+ *
+ * @example
+ * ```typescript
+ * const rtc = new BrowserRTC({
+ *   getVoiceSign: async (params) => {
+ *     const response = await fetch('/api/get-voice-sign', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params)
+ *     })
+ *     return response.json()
+ *   },
+ *   autoPlayConfirm: (opts) => {
+ *     // 处理自动播放确认
+ *     opts.onConfirm()
+ *   }
+ * })
+ *
+ * // 加入房间
+ * await rtc.join({
+ *   voiceId: 'voice-id',
+ *   userId: 'user-id',
+ *   roomId: 'room-id',
+ *   type: RTCType.RealseeBrowserRTC
+ * })
+ *
+ * // 切换麦克风
+ * await rtc.toggleMicro(true)
+ * ```
+ */
 export declare class BrowserRTC extends CoreRTC {
     type: RTCType;
     joined: boolean;
@@ -13,9 +56,29 @@ export declare class BrowserRTC extends CoreRTC {
     voiceId: string;
     private _getVoiceSign;
     private _autoPlayConfirm;
+    /**
+     * 检查系统要求
+     *
+     * 检查浏览器是否满足 TRTC 的系统要求。
+     *
+     * @returns 系统要求检查结果
+     */
     checkRequirement: () => Promise<import('trtc-js-sdk').CheckResult>;
+    /**
+     * DOM 容器（内部使用）
+     */
     private $dom;
+    /**
+     * TRTC 实例（内部使用）
+     */
     private _trtc;
+    /**
+     * 创建 BrowserRTC 实例
+     *
+     * @param options 配置选项
+     * @param options.getVoiceSign 获取语音签名的函数，必需
+     * @param options.autoPlayConfirm 自动播放确认回调（可选），用于处理浏览器的自动播放策略
+     */
     constructor(options: {
         getVoiceSign: GetVoiceSign;
         autoPlayConfirm?: (opts: {

package/dist/rtc/BrowserRTC4Chime.d.ts

@@ -3,7 +3,32 @@ import { GetVoiceSign } from '../typings/live/GetVoiceSign';
 import { RTCType } from '../typings/rtc/type';
 import { CoreRTC } from './CoreRTC';
 /**
- * amazon-chime-sdk-js 适配的rtc实现
+ * 浏览器端 Amazon Chime SDK RTC 实现
+ *
+ * 基于 Amazon Chime SDK for JavaScript 实现的浏览器端 RTC 类。
+ * 适用于在浏览器环境中使用 Amazon Chime 进行实时语音通信。
+ *
+ * @example
+ * ```typescript
+ * const rtc = new BrowserRTC4Chime({
+ *   getVoiceSign: async (params) => {
+ *     const response = await fetch('/api/get-voice-sign', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params)
+ *     })
+ *     return response.json()
+ *   },
+ *   logLevel: LogLevel.INFO
+ * })
+ *
+ * // 加入房间
+ * await rtc.join({
+ *   voiceId: 'voice-id',
+ *   userId: 'user-id',
+ *   roomId: 'room-id',
+ *   type: RTCType.RealseeBrowserChimeRTC
+ * })
+ * ```
  */
 export declare class BrowserRTC4Chime extends CoreRTC {
     type: RTCType;
@@ -23,6 +48,14 @@ export declare class BrowserRTC4Chime extends CoreRTC {
     private _autoPlayConfirm;
     private $dom;
     private $audio;
+    /**
+     * 创建 BrowserRTC4Chime 实例
+     *
+     * @param options 配置选项
+     * @param options.getVoiceSign 获取语音签名的函数，必需
+     * @param options.autoPlayConfirm 自动播放确认回调（可选），用于处理浏览器的自动播放策略
+     * @param options.logLevel 日志级别（可选），默认为 LogLevel.INFO
+     */
     constructor(options: {
         getVoiceSign: GetVoiceSign;
         autoPlayConfirm?: (opts: {
@@ -31,11 +64,14 @@ export declare class BrowserRTC4Chime extends CoreRTC {
         logLevel?: LogLevel;
     });
     /**
-     * 对audio标签初始化
+     * 初始化 DOM 元素（内部方法）
+     * 创建并挂载 audio 标签到页面
      */
     _initDom: () => void;
     /**
      * 初始化事件监听器
+     *
+     * 设置设备变化、音视频事件等监听器
      */
     initObservers: () => void;
     /**

package/dist/rtc/CoreRTC.d.ts

@@ -3,21 +3,85 @@ import { RTCProtocol } from '../typings/rtc/protocol';
 import { RTCType } from '../typings/rtc/type';
 import { Subscribe } from '../utils/subscribe';
 /**
- * rtc 基础抽象类
+ * RTC 基础抽象类
+ *
+ * 所有 RTC 实现的基类，定义了 RTC 协议的基本接口。
+ * 子类需要实现所有抽象方法和属性。
+ *
+ * @example
+ * ```typescript
+ * class MyRTC extends CoreRTC {
+ *   joined = false
+ *   micro = false
+ *   voiceId = ''
+ *   type = RTCType.Custom
+ *
+ *   async join(options) {
+ *     // 实现加入房间逻辑
+ *   }
+ *
+ *   async quit() {
+ *     // 实现退出房间逻辑
+ *   }
+ *
+ *   // 实现其他抽象方法...
+ * }
+ * ```
  */
 export declare abstract class CoreRTC extends Subscribe<RTCEventType> implements RTCProtocol {
+    /**
+     * 是否已加入语音房间
+     */
     abstract joined: boolean;
+    /**
+     * 麦克风是否开启
+     */
     abstract micro: boolean;
+    /**
+     * 当前语音房间ID
+     */
     abstract voiceId: string;
+    /**
+     * RTC 实现类型
+     */
     abstract type: RTCType;
+    /**
+     * 加入语音房间
+     *
+     * @param options 加入房间的选项
+     * @param options.voiceId 语音房间ID
+     * @param options.userId 用户ID
+     * @param options.roomId 房间ID（可选）
+     * @param options.type RTC类型
+     * @returns Promise<boolean> 是否成功加入房间
+     */
     abstract join(options: {
         voiceId: string;
         userId: string;
         roomId: string | number | undefined;
         type: RTCType;
     }): Promise<boolean>;
+    /**
+     * 退出语音房间
+     *
+     * @returns Promise<boolean> 是否成功退出房间
+     */
     abstract quit(): Promise<boolean>;
+    /**
+     * 检测麦克风权限
+     *
+     * @returns Promise<boolean> 是否有麦克风权限
+     */
     abstract detectMicro(): Promise<boolean>;
+    /**
+     * 切换麦克风状态
+     *
+     * @param flag 是否开启麦克风，不传则切换当前状态
+     * @returns Promise<boolean> 是否操作成功
+     */
     abstract toggleMicro(flag?: boolean): Promise<boolean>;
+    /**
+     * 震动（如果设备支持）
+     */
     abstract shock(): void;
 }

package/dist/rtc/VRWebViewRTC.d.ts

@@ -1,6 +1,37 @@
 import { RTCType } from '../typings/rtc/type';
 import { VRWebViewRTCOptions } from '../typings/rtc/VRWebViewRTCOptions';
 import { CoreRTC } from './CoreRTC';
+/**
+ * VR WebView RTC 实现
+ *
+ * 适用于在如视 VR App 的 WebView 或微信小程序环境中进行实时语音通信。
+ * 通过 JSBridge 与原生 App 通信，实现语音功能。
+ *
+ * @example
+ * ```typescript
+ * import JSBridge from '@realsee/jsbridge-x'
+ *
+ * const jsBridge = new JSBridge()
+ * const rtc = new VRWebViewRTC({
+ *   jsBridge,
+ *   getVoiceSign: async (params) => {
+ *     const response = await fetch('/api/get-voice-sign', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params)
+ *     })
+ *     return response.json()
+ *   }
+ * })
+ *
+ * // 加入房间
+ * await rtc.join({
+ *   voiceId: 'voice-id',
+ *   userId: 'user-id',
+ *   roomId: 'room-id',
+ *   type: RTCType.RealseeVRWebViewRTC
+ * })
+ * ```
+ */
 export declare class VRWebViewRTC extends CoreRTC {
     type: RTCType;
     joined: boolean;
@@ -11,22 +42,41 @@ export declare class VRWebViewRTC extends CoreRTC {
      */
     private _joinOptions;
     private options;
+    /**
+     * 获取 JSBridge 实例
+     *
+     * @returns JSBridge 协议实例
+     */
     get jsBridge(): import('@realsee/jsbridge-x').JSBridgeProtocol;
+    /**
+     * 创建 VRWebViewRTC 实例
+     *
+     * @param options 配置选项，包含以下属性：
+     * - jsBridge: JSBridge 实例，必需，用于与原生 App 通信
+     * - getVoiceSign: 获取语音签名的函数，必需
+     */
     constructor({ jsBridge, getVoiceSign }: VRWebViewRTCOptions);
     /**
-     * 处理用户音量
-     * @param userVolumes
+     * 处理用户音量（内部方法）
+     *
+     * @param userVolumes 用户音量数组
      */
     private handleUserVolumes;
     /**
-     * 处理弱网络情况
-     * @param weakNetwork
+     * 处理弱网络情况（内部方法）
+     *
+     * @param weakNetwork 是否为弱网络
      */
     private handleWeakNetwork;
     /**
      * 加入语音房间
-     * @param options
-     * @returns
+     *
+     * @param options 加入房间的选项
+     * @param options.voiceId 语音房间ID
+     * @param options.userId 用户ID
+     * @param options.roomId 房间ID
+     * @param options.type RTC类型
+     * @returns Promise<boolean> 是否成功加入房间
      */
     join: (options: {
         voiceId: string;

package/dist/typings/live/EventType.d.ts

@@ -6,29 +6,77 @@ import { UserInfo } from './UserInfo';
  */
 export type LiveEventType<KeyframesSnapshot> = {
     /**
-     * 带看状态变化
-     * @param state
-     * @param prevState
+     * 带看连接状态变化事件
+     *
+     * @param state 当前连接状态
+     * @param prevState 之前的连接状态（可选）
+     * @example
+     * ```typescript
+     * live.on('stateChange', (state, prevState) => {
+     *   console.log(`状态从 ${prevState} 变为 ${state}`)
+     * })
+     * ```
      */
     'stateChange'(state: LiveState, prevState?: LiveState): void;
     /**
      * 内置消息事件
-     * @param builtinMsg
+     *
+     * 当收到任何内置消息时触发，包括用户变化和房间变化。
+     *
+     * @param builtinMsg 内置消息对象
+     * @example
+     * ```typescript
+     * live.on('builtinEvent', (msg) => {
+     *   console.log('内置消息:', msg.event_type, msg.action)
+     * })
+     * ```
      */
     'builtinEvent'(builtinMsg: BuiltinMsg): void;
     /**
-     * 内置消息事件: 用户信息改变
-     * @param builtinMsg
+     * 用户信息改变事件
+     *
+     * 当用户信息发生变化时触发，是 builtinEvent 的子集。
+     *
+     * @param builtinMsg 内置消息对象，event_type 为 UserChange
+     * @example
+     * ```typescript
+     * live.on('userChange', (msg) => {
+     *   if (msg.action === BuiltinActionType.UserMicroStatus) {
+     *     console.log('麦克风状态变化:', msg.data.status)
+     *   }
+     * })
+     * ```
      */
     'userChange'(builtinMsg: BuiltinMsg): void;
     /**
-     * 内置消息事件：房间信息改变
-     * @param builtinMsg
+     * 房间信息改变事件
+     *
+     * 当房间信息发生变化时触发，是 builtinEvent 的子集。
+     *
+     * @param builtinMsg 内置消息对象，event_type 为 RoomChange
+     * @example
+     * ```typescript
+     * live.on('roomChange', (msg) => {
+     *   if (msg.action === BuiltinActionType.RoomClose) {
+     *     console.log('房间已关闭')
+     *   }
+     * })
+     * ```
      */
     'roomChange'(builtinMsg: BuiltinMsg): void;
     /**
-     * 收到其他用户的广播消息。
-     * @param evtMsg
+     * 收到其他用户的广播消息事件
+     *
+     * 当收到其他用户通过 broadcast 方法发送的自定义消息时触发。
+     *
+     * @param evtMsg 广播消息数据对象
+     * @param frontRequestId 前端请求ID，用于匹配请求和响应
+     * @example
+     * ```typescript
+     * live.on('broadcast', (data, requestId) => {
+     *   console.log('收到广播:', data, '请求ID:', requestId)
+     * })
+     * ```
      */
     'broadcast'(evtMsg: Record<string, any>, frontRequestId: string): void;
     /**

package/dist/typings/live/GetVoiceSign.d.ts

@@ -37,16 +37,36 @@ export type GetVoiceSignParams = {
     roomId: string | number;
 };
 /**
- * 获取用户语音签名的方法
- * @param {GetVoiceSignParams} params - 获取语音签名所需的参数
- * @returns {Promise<GetVoiceSignReturnType>} 返回一个Promise，解析为语音签名的相关信息
- * @property {number} sdkAppId - RTC的sdkAppId
- * @property {string} userId - RTC的用户ID
- * @property {string|number} roomId - RTC的语音房间号
- * @property {string} userSig - RTC的用户签名
+ * 获取用户语音签名的函数
+ *
+ * 用于获取加入 RTC 语音房间所需的签名信息。
+ * 通常需要调用后端 API 来生成签名。
+ *
+ * @param params 获取语音签名所需的参数，包含以下属性：
+ * - voiceId: 语音房间ID
+ * - userId: 用户ID
+ * - roomId: 房间ID
+ * @returns Promise<GetVoiceSignReturnType> 返回包含签名信息的 Promise，包含：
+ * - sdkAppId: RTC的sdkAppId
+ * - userId: RTC的用户ID
+ * - roomId: RTC的语音房间号
+ * - userSig: RTC的用户签名
+ * @example
+ * ```typescript
+ * const getVoiceSign: GetVoiceSign = async (params) => {
+ *   const response = await fetch('/api/get-voice-sign', {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify(params)
+ *   })
+ *   return response.json()
+ * }
+ * ```
  */
 export declare function GetVoiceSignFn(params: GetVoiceSignParams): Promise<GetVoiceSignReturnType>;
 /**
  * 获取用户语音签名的方法类型
+ *
+ * 用于配置 Live 实例时提供获取语音签名的函数。
  */
 export type GetVoiceSign = typeof GetVoiceSignFn;

package/dist/typings/live/UserInfo.d.ts

@@ -15,12 +15,35 @@ export declare enum UserStatus {
      */
     Replaced = 2
 }
+/**
+ * 内存中的用户状态枚举
+ *
+ * 用于表示用户在内存中的状态，与 UserStatus 不同，这个状态更详细地描述了用户的生命周期。
+ */
 export declare enum MemUserStatus {
+    /**
+     * 等待进入房间
+     */
     WAIT_ENTER = "WAIT_ENTER",
+    /**
+     * 在线
+     */
     ONLINE = "ONLINE",
+    /**
+     * 已离开
+     */
     LEAVE = "LEAVE",
+    /**
+     * 被踢出
+     */
     KICK_OUT = "KICK_OUT",
+    /**
+     * 被替换
+     */
     BE_REPLACE = "BE_REPLACE",
+    /**
+     * 异常状态
+     */
     EXCEPTION = "EXCEPTION"
 }
 /**
@@ -85,19 +108,66 @@ export type UserInfo = {
      */
     extension?: UserInfoExt;
 };
+/**
+ * 用户权限配置接口
+ *
+ * 定义了用户在带看房间中的各种权限。所有权限都是布尔值，true 表示拥有该权限。
+ */
 export interface Permission {
+    /**
+     * 切换更多 VR 场景的权限
+     */
     more_vr_scene: boolean;
+    /**
+     * 邀请其他用户进入房间的权限
+     */
     invite_other: boolean;
+    /**
+     * 控制自己麦克风的权限
+     */
     control_own_micro: boolean;
+    /**
+     * 控制其他用户麦克风的权限
+     */
     control_other_micro: boolean;
+    /**
+     * 查看自己麦克风状态的权限
+     */
     view_own_micro_status: boolean;
+    /**
+     * 查看其他用户麦克风状态的权限
+     */
     view_other_micro_status: boolean;
+    /**
+     * 关闭带看房间的权限
+     */
     close_live_room: boolean;
+    /**
+     * 申请获取其他用户电话的权限
+     */
     apply_other_phone: boolean;
+    /**
+     * 动态进入房间的权限
+     */
     dynamic_enter: boolean;
+    /**
+     * 同步帧数据的权限
+     */
     sync_frame: boolean;
+    /**
+     * 改变用户角色的权限
+     */
     transfer_role: boolean;
+    /**
+     * 改变其他用户状态的权限（如踢出用户）
+     */
     change_other_status: boolean;
+    /**
+     * 控制其他用户全量同步帧数据权限的权限
+     */
     control_other_sync: boolean;
+    /**
+     * 其他扩展权限点
+     */
     extension: Record<string, boolean>;
 }

package/dist/typings/rtc/eventType.d.ts

@@ -1,29 +1,76 @@
 import { UserVolume } from '../live/UserVolume';
 import { RTCJoinedInfo } from './joinedInfo';
 /**
- * RTC 异步事件类型。
+ * RTC 异步事件类型
+ *
+ * 定义了 RTC 实例可以触发的所有事件类型
  */
 export type RTCEventType = {
     /**
-     * 错误\异常
-     * @param error
+     * RTC 错误或异常事件
+     *
+     * @param error 错误对象或加入房间信息
+     * @example
+     * ```typescript
+     * rtc.on('error', (error) => {
+     *   console.error('RTC 错误:', error)
+     * })
+     * ```
      */
     "error"(error: Error | RTCJoinedInfo): void;
     /**
-     * 即将加入房间。
+     * 即将加入房间事件
+     *
+     * 在开始加入房间流程时触发。
+     *
+     * @example
+     * ```typescript
+     * rtc.on('joinWillStart', () => {
+     *   console.log('开始加入房间...')
+     * })
+     * ```
      */
     "joinWillStart"(): void;
     /**
-     * 成功加入语音房间。
+     * 成功加入语音房间事件
+     *
+     * 当成功加入语音房间时触发。
+     *
+     * @example
+     * ```typescript
+     * rtc.on('joined', () => {
+     *   console.log('已成功加入语音房间')
+     * })
+     * ```
      */
     "joined"(): void;
     /**
-     * 弱网提醒事件。
+     * 弱网络提醒事件
+     *
+     * 当检测到网络质量较差时触发。
+     *
+     * @example
+     * ```typescript
+     * rtc.on('weakNetwork', () => {
+     *   console.warn('网络质量较差，可能影响语音通话')
+     * })
+     * ```
      */
     "weakNetwork"(): void;
     /**
-     * 每个用户的音量。
-     * @param userVolumes
+     * 用户音量事件
+     *
+     * 当收到用户音量信息时触发，用于显示用户说话状态。
+     *
+     * @param userVolumes 用户音量数组，包含每个用户的音量信息
+     * @example
+     * ```typescript
+     * rtc.on('userVolumes', (volumes) => {
+     *   volumes.forEach(volume => {
+     *     console.log(`用户 ${volume.userId} 音量: ${volume.volume}`)
+     *   })
+     * })
+     * ```
      */
     "userVolumes"(userVolumes: UserVolume[]): void;
     /**

package/dist/utils/appendUri.d.ts

@@ -1 +1,18 @@
+/**
+ * 向 URI 追加查询参数
+ *
+ * 将查询参数追加到 URI 中，如果 URI 已有查询参数，会合并新的参数。
+ *
+ * @param uri 原始 URI 字符串
+ * @param query 要追加的查询参数对象
+ * @returns 追加查询参数后的完整 URI 字符串
+ * @example
+ * ```typescript
+ * appendUri('wss://example.com/live', { ticket: 'abc123', force: 1 })
+ * // 返回: 'wss://example.com/live?ticket=abc123&force=1'
+ *
+ * appendUri('wss://example.com/live?room=1', { ticket: 'abc123' })
+ * // 返回: 'wss://example.com/live?room=1&ticket=abc123'
+ * ```
+ */
 export declare function appendUri(uri: string, query?: Record<string, string | number>): string;

package/dist/utils/uuid.d.ts

@@ -1,4 +1,14 @@
 /**
- * 基于伪随机数生成 **uuid**。
+ * 基于伪随机数生成 UUID
+ *
+ * 生成一个符合 UUID v4 格式的字符串（但不完全符合 RFC 4122 标准）。
+ * 格式：xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx
+ *
+ * @returns 生成的 UUID 字符串
+ * @example
+ * ```typescript
+ * const id = uuid()
+ * console.log(id) // 例如: 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
+ * ```
  */
 export declare function uuid(): string;

package/docs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.