npm package: 4u-webrtc-sdk
Description: WebRTC SDK for video/audio communication
Latest version: 1.0.0

# 2.5D数字人集成说明.md
# WebRTC SDK 集成文档

## 1. 安装与引入

### 1.1 安装(还未发布)
```bash
npm install 4u-webrtc-sdk
```

### 1.2 引入方式
ES Module方式:
```javascript
import { LiveRoom } from '4u-webrtc-sdk';
```
UMD方式:
```html
<script src="dist/index.umd.js"></script>
<script>
const { LiveRoom } = WebRTCSDK;
</script>
```
## 2. 基础配置

### 2.1 HTML元素
需要准备video和audio元素用于播放远端流:
```html
<video 
  class="rtc-video" 
  playsinline 
  autoplay 
  muted
  webkit-playsinline=""
  x5-playsinline
></video>
<audio class="rtc-audio" autoplay></audio>
```

### 2.2 配置参数说明

| 参数类别       | 参数名            | 类型        | 必填 | 说明                                   |
| -------------- | ----------------- | ----------- | ---- | -------------------------------------- |
| **视频元素**   | rtcVideo          | HTMLElement | 是   | 用于播放远端视频流的video元素          |
|                | rtcAudio          | HTMLElement | 是   | 用于播放远端音频流的audio元素          |
| **媒体配置**   | ROOM_CONSTRAINTS  | Object      | 是   | 媒体约束配置                           |
|                | - video           | Boolean     | 是   | 是否开启视频                           |
|                | - audio           | Boolean     | 是   | 是否开启音频（本地收入视频）           |
| **连接参数**   | USER_ID           | String      | 是   | 用户唯一标识（世友科技分配）           |
|                | LIVE_ROOM_URL     | String      | 是   | 信令服务器地址（世友科技分配）         |
|                | SINGALING_WSS_URL | String      | 是   | WebSocket服务器地址 （世友科技分配）   |
|                | APP_ID            | String      | 否   | 应用ID，默认使用（"3f4aG7b2H9i1k5Mn"） |
| **WebRTC配置** | configuration     | Object      | 否   | WebRTC配置项                           |
|                | - sdpSemantics    | String      | 否   | SDP语义配置 （默认"unified-plan"）      |
|                | - iceServers      | Array       | 否   | TURN/STUN服务器配置 （世友科技分配）   |


示例代码：
```javascript
const config = {
  rtcVideo: document.querySelector('.rtc-video'),
  rtcAudio: document.querySelector('.rtc-audio'),
  ROOM_CONSTRAINTS: {
    video: false,
    audio: true
  },
  USER_ID: 'xxx',
  LIVE_ROOM_URL: 'https://xxx',
  SINGALING_WSS_URL: 'wss://xxx',
  APP_ID: '3f4aG7b2H9i1k5Mn',
  configuration: {
    sdpSemantics: "unified-plan",
    iceServers: [{
      urls: 'turn:xxx:3478',
      credential: '123456',
      username: 'admin'
    }]
  }
};

const room = new LiveRoom(config);
```

## 3. 核心功能 API

### 3.1 连接流程

#### 3.1.1 基本流程说明

```mermaid
sequenceDiagram
    participant Client
    participant Signaling
    participant RTC
    participant Server

    Client->>+Signaling: 1. initInstance({...events})
    Note over Client,Signaling: 同时注册message, error, close, open
    Signaling-->>-Client: 返回实例对象
  


    Client->>+Server: 2. connectRoom()
    Server-->>-Client: 房间连接成功

    Client->>+RTC: 3. startRtc()【可选】
    RTC-->>-Client: RTC连接成功

    Client->>+Signaling: 4. 发送消息
    Note over Client,Signaling: 按照协议格式发送
```
示例代码：
```javascript
// 1. 开始建立房间、注册event事件：message、error、close、open,获取rtc实例、信令实例对象
const { rtc, signaling, roomid, APP_ID } = await room.initInstance({
  message: (data) => {
      console.log("[Signaling] 🚀 收到 WS 消息:", data);
  },
  error: (error) => {
      console.error("[Signaling] 🚀 收到 WS 错误:", error);
  },
  close: () => {
      console.log("[Signaling] 🚀 收到 WS 关闭");
  },
  open: () => {
      console.log("[Signaling] 🚀 收到 WS 打开");
  },
});
// 2. 连接房间
await room.connectRoom();
console.log('房间连接成功');

// 3. 开始RTC连接
await room.startRtc();
console.log('RTC连接成功');

// 4. 发送消息(按照协议发送)
// 文本消息参数：
const textParams = {
  type: 'message_text',
  text: 'Text文本'
};
signaling.send(textParams);
// 打断数字人操作参数：
const breakParams = {
  type: 'break'
};
signaling.send(breakParams);
```

#### 3.1.2 详细步骤说明

1. **初始化实例**
   ```javascript
   const { rtc, signaling, roomid, APP_ID } = await room.initInstance({
     message: (data) => {
       console.log("[Signaling] 🚀 收到 WS 消息:", data);
     },
     error: (error) => {
       console.error("[Signaling] 🚀 收到 WS 错误:", error);
     },
     close: () => {
       console.log("[Signaling] 🚀 收到 WS 关闭");
     },
     open: () => {
       console.log("[Signaling] 🚀 收到 WS 打开");
     },
   });
   ```

2. **连接房间**
   - 通过 `connectRoom()` 建立与服务器的连接
   - 等待连接成功确认

3. **建立RTC连接**
   - 调用 `startRtc()` 开始音视频传输
   - 等待 RTC 连接建立完成

4. **消息通信**
   
   发送消息格式：
   | 消息类型 | 参数格式 | 说明 |
   |----------|----------|------|
   | `message_text` | `{ type: 'message_text', text: 'Text文本' }` | 发送文本消息 |
   | `break` | `{ type: 'break' }` | 发送打断指令 |

   接收消息格式：
   | msg_type | 说明 | 数据格式 |
   |----------|------|----------|
   | `asr` | 语音识别结果 | `{ msg_type: 'asr', data: {...} }` |
   | `tts` | 返回的文本内容 | `{ msg_type: 'tts', data: {...} }` |
   | `quit` | 退出房间通知 | `{ msg_type: 'quit', data: {...} }` |

### 3.2 断开连接

#### 3.2.1 断开方式说明

1. **完全断开**
   ```javascript
   await room.disconnect();  // 同时断开信令和RTC连接
   ```

2. **仅停止RTC**
   ```javascript
   await room.stopRtc();    // 只断开RTC连接，保持信令连接
   ```

#### 3.2.2 注意事项

1. 断开连接为异步操作，建议使用 `await` 等待操作完成
2. 完全断开后如需重连，需要重新执行完整的连接流程
3. 仅停止 RTC 后，可以通过 `startRtc()` 重新建立 RTC 连接
4. 建议在组件销毁或页面关闭时调用断开连接，避免资源泄露

## 5. 注意事项

1. 确保在https环境下使用,或localhost开发环境

2. 在移动端需要注意添加playsinline等属性以支持自动播放

3. 注意及时清理资源,断开连接时调用disconnect()

4. 建议在组件销毁时移除所有事件监听


##  7.快速体验Demo

### 7.1启动本地服务器
```bash
# 1. 进入server目录
cd server

# 2. 安装依赖
npm install

# 3. 启动服务器(会自动生成测试证书)
npm start
```

### 7.2 运行Demo
```bash
# 1. 项目根目录安装依赖
npm install

# 2. 构建SDK
npm run build

# 3. 用浏览器打开demo页面
https://localhost:3000/demo/index.html
```

### 7.3 Demo功能说明

Demo页面提供以下功能按钮:
- 连接: 建立WebSocket连接并创建房间
- 断开: 断开所有连接
- 停止RTC: 仅停止RTC连接
- 开始RTC: 重新建立RTC连接


###  Demo注意事项

1. 确保3000端口未被占用或者修改server/index.ts中的端口号

2. Demo使用了固定的测试用户ID,实际使用时需要使用真实的用户ID

3. Demo默认关闭了音视频,可以通过修改ROOM_CONSTRAINTS开启

4. 可以打开浏览器控制台查看详细的连接日志