@realsee/live 0.7.3 → 0.7.5

package/README.md

@@ -39,23 +39,34 @@ yarn add @realsee/live
 
 简单使用样例（先不考虑实时语音能力）：
 
-```js
+```typescript
 import { createLive } from '@realsee/live'
 
-const live = createLive({
+// 定义帧数据类型（可选，但推荐使用 TypeScript）
+interface MyKeyframes {
+  camera: { position: [number, number, number] }
+  annotation: { text: string; position: [number, number] }
+}
+
+const live = createLive<MyKeyframes>({
   url: 'wss://ws-access.realsee.com/***/?=xxx' /* 连接 WebSocket 服务的 URL */,
   getTicket: async () => {
     /* 获取带看"门票"的回调函数 */
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
   },
 })
+
+// 连接带看
+await live.connect()
 ```
 
 在创建 `live` 实例时配置了两个参数：
 
-- `url`：连接 WebSocket 服务的 URL，如果在创建 `live` 实例阶段并不知道 URL ，您可以在合适的时机通过 `live.connect({ url })` 方法进行 WebScoket 连接。
-- `getTicket()`：是一个异步回调函数，其返回值是连接 WebScoket 服务的 **"门票"**，关于如何获取 `ticket` 请查阅 [VR 带看 API](https://developers.realsee.com/docs/#/docs/live/server/README)。
+- `url`：连接 WebSocket 服务的 URL（可选），如果在创建 `live` 实例阶段并不知道 URL，您可以在合适的时机通过 `live.connect({ url })` 方法进行 WebSocket 连接。
+- `getTicket()`：是一个异步回调函数（可选），其返回值是连接 WebSocket 服务的 **"门票"**，关于如何获取 `ticket` 请查阅 [VR 带看 API](https://developers.realsee.com/docs/#/docs/live/server/README)。也可以在 `connect` 时提供。
 
-> 关于 `createLive()` 函数的更多参数配置请参考 [LiveOptions](https://unpkg.com/@realsee/live/docs/interfaces/live.LiveOptions.html) 。
+> 关于 `createLive()` 函数的更多参数配置请参考 [LiveOptions](https://unpkg.com/@realsee/live/docs/interfaces/live.LiveOptions.html) 文档。
 
 获取实例 `live` 之后，可以做很多有趣的事情。但在讲述详细用途之前，先简单介绍下 **Live** 中的 **消息系统**。
 
@@ -78,12 +89,12 @@ const live = createLive({
 
 以 [Five](https://developers.realsee.com/docs/#/docs/five/web/quickstart) 同屏为例
 
-```js
+```typescript
 // 发送本地 帧数据 (Five State)
 live.sendKeyframe('five', { panoIndex: 13 })
 
 // 接收远程 帧数据 (Five State)
-live.keyframes.on('five', (newState, prevState) => {
+live.keyframes.on('five', (newState, prevState, frontRequestId) => {
   // 可以拿最新的 `newState` 更新本地 UI 状态
 })
 ```
@@ -94,61 +105,65 @@ live.keyframes.on('five', (newState, prevState) => {
 
 **Live** 有会话房间的概念，当您成功连接 WebSocket 服务之后等同于您作为一个用户加入了一个房间。此房间用户除了您之外还会有其他用户，您可以通过如下方式获取或更新用户信息：
 
-```js
+```typescript
 // 属性：获取本地用户信息
 live.selfInfo
 
 // 属性：获取当前房间内所有用户列表
 live.userList
 
+// 属性：获取房间信息
+live.roomInfo
+
 // 方法：更新本地用户信息
 live.setSelfInfo({})
 
 // 事件：本地用户信息发生变更
-live.on('selfInfoUpdate', (userInfo) => {})
+live.on('selfInfoUpdate', (userInfo, frontRequestId) => {})
 
 // 事件：房间用户列表信息发生变更
-live.on('userListUpdate', (userList) => {})
+live.on('userListUpdate', (userList, frontRequestId) => {})
 ```
 
 ### 广播消息
 
 除了帧数据和房间信息之外，还可以用事件的形式向房间内的其他用户广播消息：
 
-```js
-live.broadcast(data /* 广播的数据 */, ['user_id_1', 'user_id_2'] /* 收到此用户的userId */)
+```typescript
+live.broadcast(
+  data /* 广播的数据 */, 
+  ['user_id_1', 'user_id_2'] /* 收到此消息的用户ID列表 */,
+  0 /* 超时时间（毫秒），0 表示不超时 */
+)
 ```
 
 此时，房间内用户 Id 为 `user_id_1`、`user_id_2` 的用户会收到此广播消息（其他用户无感知）：
 
-```js
-live.on('broadcast', (data /* 广播的数据 */) => {})
+```typescript
+live.on('broadcast', (data /* 广播的数据 */, frontRequestId) => {})
 ```
 
 更多的例子请查看 [Live API](https://unpkg.com/@realsee/live/docs/index.html) 文档 。
 
 ## 事件监听
 
-**Live** 提供 `WebSocket 事件`、`live 事件` 和 `RTC 事件` 三类异步事件的监听。
+**Live** 提供 `带看事件` 和 `RTC 事件` 两类异步事件的监听。
 
-其中， `WebSocket 事件`、`live 事件` 都可以通过 `live.on('/*事件名*/', /*事件回调*/)` 的方式监听。
+所有事件都可以通过 `live.on('/*事件名*/', /*事件回调*/)` 的方式监听。
 
-比如监听 WebSocket 状态发生变更：
+比如监听连接状态变化：
 
-```ts
-live.on('ws.readyStateUpdate', (readyState: WebSocketState) => {
-  console.log(readyState) // readyState 即是最新的 WebScoket 状态
+```typescript
+live.on('stateChange', (state, prevState) => {
+  console.log(`状态从 ${prevState} 变为 ${state}`)
 })
 ```
 
-### WebSocket 事件
+### 带看连接状态
 
-- `ws.beforeConnect(reConnect?: number): void` WebSocket 完成连接之后。
-- `ws.afterConnect(reConnect?: number): void` WebSocket 完成连接之前。
+**Live** 前后端服务交互是基于 WebSocket 长链接的。一次带看成功进入、退出的标识由连接状态 `OPEN`、`CLOSED` 体现。因此，所有 **VRTC** 相关的事件处理逻辑应保证在 `OPEN` 状态之后进行。
 
-- `ws.readyStateUpdate(readyState: WebSocketState): void` WebSocket 完成状态发生变更。
-
-**WebSocket 连接状态枚举表：**
+**连接状态枚举表：**
 
 | 状态名称       | 状态描述   |
 | -------------- | ---------- |
@@ -158,47 +173,54 @@ live.on('ws.readyStateUpdate', (readyState: WebSocketState) => {
 | CLOSING        | 关闭中     |
 | CLOSED         | 关闭成功   |
 
-**Live** 前后端服务交互是基于 WebSocket 长链接的。一次带看成功进入、退出的标识由 WebSocket 的状态 `OPEN`、`CLOSED`体现。 因此，所有 **VRTC** 相关的事件处理逻辑应保证在`OPEN`
-事件之后进行。
+### 带看事件
+
+- `stateChange(state: LiveState, prevState?: LiveState): void` - 带看连接状态变化事件
+
+- `builtinEvent(builtinMsg: BuiltinMsg): void` - 接收服务端推送的内置事件消息（包括用户变化和房间变化）
 
-### live 事件
+- `userChange(builtinMsg: BuiltinMsg): void` - 用户信息改变事件（是 builtinEvent 的子集，event_type 为 UserChange）
 
-- `broadcast(evtMsg: Record<string, any>, frontRequestId: string): void` 接收其他用户的广播消息。
+- `roomChange(builtinMsg: BuiltinMsg): void` - 房间信息改变事件（是 builtinEvent 的子集，event_type 为 RoomChange）
 
-- `builtinEvent(builtinMsg: BuiltinMsg): void` 接收服务端推送的内置事件消息。
+- `broadcast(evtMsg: Record<string, any>, frontRequestId: string): void` - 接收其他用户的广播消息
 
-- `keyframes(keyframes: Partial<Snapshot>, frontRequestId: string): void` 接收其他用户的帧数据。
+- `keyframes(keyframes: Partial<Snapshot>, frontRequestId: string): void` - 接收其他用户的帧数据
 
-- `readyKeyframeSync(lastKeyframe: Partial<Snapshot>): void` 表明帧同步行为已就绪。
+- `readyKeyframeSync(lastKeyframe: Partial<Snapshot>): void` - 表明帧同步行为已就绪（**已废弃**，请使用 `keyframes` 事件）
 
-- `selfInfoUpdate(userInfo: UserInfo, frontRequestId: string): void` 自身的信息发生变更。
+- `selfInfoUpdate(userInfo: UserInfo, frontRequestId: string): void` - 自身的信息发生变更
 
-- `userListUpdate(userList: UserInfo[], frontRequestId: string): void` 用户列信息表发生变更。
+- `userListUpdate(userList: UserInfo[], frontRequestId: string): void` - 用户列表信息发生变更
+
+- `kickOut(): void` - 被踢出房间
+
+- `error(liveMsg: LiveMsg): void` - 服务端推送出现异常
 
 `live` 实例提供了很多诸如`live.connect()`、`live.broadcast()`、`live.sendKeyframe()`等方法，这些方法都是异步反馈且可能会影响房间内的其他用户。
 您可以通过监听以上事件来获知这些影响。
 
-需要注意的是 `readyKeyframeSync` 事件是可进行帧同步的节点标识，收到此事件后您的帧同步行为才生效。
-
 ### RTC 事件
 
-- `error(error: Error): void` 异常事件。
+RTC 相关事件通过 `live.$RTC.on('/*事件名*/', /*事件回调*/)` 方式来监听。
 
-- `initWillStart(): void` 即将初始化事件。
+- `error(error: Error): void` - 异常事件
 
-- `inited(): void` 初始化完成事件。
+- `initWillStart(): void` - 即将初始化事件
 
-- `joinWillStart(): void` 即将加入语音房间事件。
+- `inited(): void` - 初始化完成事件
 
-- `joined(): void` 成功加入语音房间事件。
+- `joinWillStart(): void` - 即将加入语音房间事件
 
-- `userVolumes(userVolumes: UserVolume[]): void` 房间内每个说话用户的音量。
+- `joined(info: RTCJoinedInfo): void` - 成功加入语音房间事件
 
-- `weakNetwork(): void` 弱网提醒事件。
+- `userVolumes(userVolumes: UserVolume[]): void` - 房间内每个说话用户的音量
 
-`live.$RTC` 实例需满足 [RTC 协议](https://unpkg.com/@realsee/live/docs/interfaces/rtc.RTCProtocol.html)，其事件通过 `live.$RTC.on('/*事件名*/', /*事件回调*/)` 方式来监听，比如监听语音房间内正在说话的用户及其音量：
+- `weakNetwork(): void` - 弱网提醒事件
 
-```ts
+比如监听语音房间内正在说话的用户及其音量：
+
+```typescript
 live.$RTC.on('userVolumes', (userVolumes: UserVolume[]) => {
   console.log(userVolumes) // userVolumes 正在说话的用户及其音量数据。
 })
@@ -206,30 +228,17 @@ live.$RTC.on('userVolumes', (userVolumes: UserVolume[]) => {
 
 ### 异常处理
 
-- `ws.error(error: WebSocketError): void` WebSocket 连接出现异常。
-
-**WebSocket 错误状态枚举表：**
-
-| 错误字段         | 错误描述                                                                                  | 触发场景                                                                              |
-| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| Close            | 错误类型枚举参照[CloseEvent](https://developer.mozilla.org/zh-CN/docs/Web/API/CloseEvent) | 错误原因参照[CloseEvent](https://developer.mozilla.org/zh-CN/docs/Web/API/CloseEvent) |
-| Error            |
-| MicroAuth        | 麦克风授权错误                                                                            | 语音功能获取麦克风授权失败                                                            |
-| DuplicateConnect | 重复连接                                                                                  | 使用相同的 WS 链接申请连接                                                            |
-| IllegalURL       | 非法的 WS 链接                                                                            | 传入的 WS 链接不合法                                                                  |
-| Unknown          | 未知错误                                                                                  | 其他未被枚举的错误原样返回                                                            |
-
-- `error(liveMsg: LiveMsg): void` 服务端推送出现异常。
+- `error(liveMsg: LiveMsg): void` - 服务端推送出现异常。
 
 与 WebSocket 通信的结构体`LiveMsg`格式如下：
 
 | 名称            | 类型                | 描述                                                                                                  |
 | --------------- | ------------------- | ----------------------------------------------------------------------------------------------------- |
-| appId           | string              |
+| appId           | string              | 应用ID                                                                                                 |
 | code            | string              | 返回码，详情参照[服务端 API Code 码表](https://developers.realsee.com/docs/#/docs/live/server/README) |
 | command         | 指令                | WebSocket 通信指令类型，详情请查看[Live API](https://unpkg.com/@realsee/live/docs/index.html) 文档    |
 | data            | Record<string, any> | 本条指令对应的业务数据                                                                                |
-| frontRequestId: | string              | 前端的请求 ID，由 WS 服务原样透传回前端                                                               |
+| frontRequestId  | string              | 前端的请求 ID，由 WS 服务原样透传回前端                                                               |
 | message         | string              | 返回描述                                                                                              |
 | requestId       | string              | 后端请求 ID                                                                                           |
 | roomCode        | string              | 带看房间号                                                                                            |
@@ -237,7 +246,7 @@ live.$RTC.on('userVolumes', (userVolumes: UserVolume[]) => {
 
 当 WebSocket 推送的数据结构体不满足 `LiveMsg` 或者 `code` 值不为 `SUCCESS` 时会以 `error` 事件的形式抛出来。
 
-- `error(error: Error): void` RTC 语音出现异常。
+- `error(error: Error): void` - RTC 语音出现异常。
 
 > RTC 语音不同容器或 RTC 解决方案不同，其错误信息内容可能不完全一致。
 
@@ -253,30 +262,44 @@ live.$RTC.on('userVolumes', (userVolumes: UserVolume[]) => {
 
 如果是 iOS/Android App（已接入如视 VRTC 容器 SDK）
 
-```js
+```typescript
 import JSBridge from '@realsee/jsbridge-x'
 import { createLive, VRWebViewRTC } from '@realsee/live'
 
 const jsBridgeInstance = new JSBridge()
 
 const rtcInstance = new VRWebViewRTC({
-  jsBridge,
-  getVoiceSign: () => {},
+  jsBridge: jsBridgeInstance,
+  getVoiceSign: async (params) => {
+    // 获取语音签名
+    const response = await fetch('/api/get-voice-sign', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    return response.json()
+  },
 })
 
 const live = createLive({
   rtc: rtcInstance,
-  getTicket: async () => '',
+  getTicket: async () => {
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
+  },
 })
 ```
 
 提供 RTC 实例配置参数之后，语音的连接、断开、重连等逻辑就托管给了 **Live** 。您可以通过 live 实例上的 `$RTC` 命名空间访问语音相关的状态和事件。
 
-```js
+```typescript
 // 状态：用户是否成功加入语音房间
 live.$RTC.joined
 // 状态：用户麦克风状态
 live.$RTC.micro
+// 状态：当前语音房间ID
+live.$RTC.voiceId
+// 状态：RTC 类型
+live.$RTC.type
 // 监听用户音量变化
 live.$RTC.on('userVolumes', (userVolumes) => {})
 ```
@@ -294,22 +317,33 @@ live.$RTC.on('userVolumes', (userVolumes) => {})
 ```shell
 # 需要您自行安装
 yarn add trtc-js-sdk
+# 或
+npm install trtc-js-sdk
 ```
 
 使用方式：
 
-```tsx
+```typescript
 import { createLive, BrowserRTC } from '@realsee/live'
 
 const rtcInstance = new BrowserRTC({
-  getVoiceSign: () => {},
+  getVoiceSign: async (params) => {
+    const response = await fetch('/api/get-voice-sign', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    return response.json()
+  },
   // 可选：处理自动播放策略
   // autoPlayConfirm: ({ onConfirm }) => showDialogThen(onConfirm)
 })
 
 const live = createLive({
   rtc: rtcInstance,
-  getTicket: async () => '',
+  getTicket: async () => {
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
+  },
 })
 ```
 
@@ -320,20 +354,31 @@ const live = createLive({
 ```shell
 # 需要您自行安装
 yarn add amazon-chime-sdk-js
+# 或
+npm install amazon-chime-sdk-js
 ```
 
 使用方式：
 
-```tsx
+```typescript
 import { createLive, BrowserRTC4Chime } from '@realsee/live'
 
 const rtcInstance = new BrowserRTC4Chime({
-  getVoiceSign: () => {},
+  getVoiceSign: async (params) => {
+    const response = await fetch('/api/get-voice-sign', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    return response.json()
+  },
 })
 
 const live = createLive({
   rtc: rtcInstance,
-  getTicket: async () => '',
+  getTicket: async () => {
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
+  },
 })
 ```
 
@@ -341,15 +386,25 @@ const live = createLive({
 
 使用方式：
 
-```tsx
-import { createLive } from '@realsee/live'
+```typescript
+import { createLive, BuiltInRTCType } from '@realsee/live'
 
 const live = createLive({
   useBuiltInRTC: true, // 使用内置rtc
   builtInRTCType: BuiltInRTCType.RealseeXChimeRTC, // 内置 rtc 类型，不填则默认trtc，chime请指明
   useBuiltInJsBridge: true, // 使用内置的jsBridge
-  getVoiceSign, // 内置的rtc还是要把 getVoiceSign 方法传递进去
-  getTicket: async () => '' /* 必须提供 */,
+  getVoiceSign: async (params) => {
+    // 内置的rtc还是要把 getVoiceSign 方法传递进去
+    const response = await fetch('/api/get-voice-sign', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    return response.json()
+  },
+  getTicket: async () => {
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
+  },
 })
 
 // 可以直接使用里面的 jsBridge, 该实例由 @realsee/jsbridge-x 提供支持
@@ -366,7 +421,7 @@ jsBridge.ready().then(() => console.info(`${jsBridge.webViewType} jsBridge is re
 
 步骤一：新建文件 `LiveReact.ts` 并创建您自己的 `LiveReact` 实例。
 
-```tsx
+```typescript
 import { createLiveReact } from '@realsee/live'
 
 /** 定义帧数据快照结构 */
@@ -384,7 +439,18 @@ interface Snapshot {
 /** 通过 `createLiveReact()` 函数创建实例*/
 
 const LiveReact = createLiveReact<Snapshot>({
-  getTicket: async () => '' /* 必须提供 */,
+  getTicket: async () => {
+    const response = await fetch('/api/get-ticket')
+    return response.json().ticket
+  },
+  getVoiceSign: async (params) => {
+    const response = await fetch('/api/get-voice-sign', {
+      method: 'POST',
+      body: JSON.stringify(params)
+    })
+    return response.json()
+  },
+  useBuiltInRTC: true,
 })
 
 export default LiveReact
@@ -393,31 +459,87 @@ export default LiveReact
 export const LiveProvider = LiveReact.LiveProvider
 export const useConnect = LiveReact.useConnect
 export const useKeyframe = LiveReact.useKeyframe
-// export ..
+export const useLiveAction = LiveReact.useLiveAction
+export const useLiveState = LiveReact.useLiveState
+export const useUserList = LiveReact.useUserList
+// export ...
 ```
 
 步骤二：通过 `LiveProvider` 将 `live` 实例集成到 `React` 的 [Context](https://reactjs.org/docs/context.html) 上下文环境中。
 
-```jsx
+```tsx
 import { LiveProvider } from './LiveReact'
 
 ReactDOM.render(
   <LiveProvider>
     <RootApp />
   </LiveProvider>,
-  containter,
+  container,
 )
 ```
 
 步骤三：在您的 `React` 函数组件中使用相关 `Hooks` 函数。
 
-```jsx
-import { useConnect } from './LiveReact'
+### 可用的 React Hooks
+
+**Live** 提供了丰富的 React Hooks，方便在 React 组件中使用：
+
+- `useLiveInstance()` - 获取当前 Live 实例
+- `useRTCInstance()` - 获取当前 RTC 实例
+- `useConnect()` - 获取连接函数
+- `useKeyframe(key)` - 获取指定键的帧数据状态和更新函数（类似 useState）
+- `useKeyframeUpdateCallback(key, callback, deps)` - 监听指定键的帧数据更新回调
+- `useLiveAction()` - 获取带看操作函数（connect, sendKeyframe, toggleMicro, broadcast, exit, kick, forbidMicro, forbidSync, getFramesByKey, setSelfInfo, updateStatus）
+- `useLiveEventCallback(name, callback, deps)` - 监听带看事件
+- `useLiveState()` - 获取带看连接状态
+- `useRTCAction()` - 获取 RTC 操作函数（join, quit, toggleMicro, detectMicro, shock）
+- `useRTCEventCallback(name, callback, deps)` - 监听 RTC 事件
+- `useSelfInfo()` - 获取和更新用户信息（类似 useState）
+- `useKeyframesSnapshot()` - 获取所有帧数据快照
+- `useUserList()` - 获取用户列表
+
+使用示例：
+
+```tsx
+import { useConnect, useLiveAction, useKeyframe, useLiveState, LiveState } from './LiveReact'
 
 function ReconnectBtn() {
   const connect = useConnect()
+  const liveState = useLiveState()
+
+  return (
+    <button 
+      onClick={() => connect({ 
+        url: 'wss://example.com/live',
+        getTicket: async () => {
+          const response = await fetch('/api/get-ticket')
+          return response.json().ticket
+        }
+      })}
+      disabled={liveState === LiveState.CONNECTING || liveState === LiveState.OPEN}
+    >
+      {liveState === LiveState.OPEN ? '已连接' : '重新连接'}
+    </button>
+  )
+}
+
+function CameraControl() {
+  const [camera, setCamera] = useKeyframe('camera')
+  const { sendKeyframe } = useLiveAction()
+
+  const handleMove = () => {
+    const newCamera = { position: [1, 2, 3], rotation: [0, 0, 0] }
+    setCamera(newCamera) // 会自动同步到其他用户
+    // 或者使用 sendKeyframe
+    // sendKeyframe('camera', newCamera)
+  }
 
-  return <button onClick={() => connect()}>重新连接</button>
+  return (
+    <div>
+      <p>相机位置: {camera?.position?.join(', ')}</p>
+      <button onClick={handleMove}>移动相机</button>
+    </div>
+  )
 }
 ```
 
@@ -429,5 +551,5 @@ function ReconnectBtn() {
 ## 相关文档链接
 
 - [@realsee/five](https://www.npmjs.com/package/@realsee/five)
-- [@realsee/jsbridge](https://www.npmjs.com/package/@realsee/jsbridge)
+- [@realsee/jsbridge-x](https://www.npmjs.com/package/@realsee/jsbridge-x)
 - [如视开发者中心 VRTC 服务](https://developers.realsee.com/docs/#/docs/live/README)