2.5D数字人集成说明.md

WebRTC SDK 集成文档

1. 安装与引入

1.1 安装(还未发布)

npm install 4u-webrtc-sdk

1.2 引入方式

ES Module方式:

import { LiveRoom } from '4u-webrtc-sdk';

UMD方式:

<script src="dist/index.umd.js"></script>
<script>
const { LiveRoom } = WebRTCSDK;
</script>

2. 基础配置

2.1 HTML元素

需要准备video和audio元素用于播放远端流:

<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服务器配置 （世友科技分配） |

示例代码：

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 基本流程说明

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: 按照协议格式发送

示例代码：

// 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. 初始化实例

   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. 完全断开

   await room.disconnect();  // 同时断开信令和RTC连接

2. 仅停止RTC

   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启动本地服务器

# 1. 进入server目录
cd server

# 2. 安装依赖
npm install

# 3. 启动服务器(会自动生成测试证书)
npm start

7.2 运行Demo

# 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. 可以打开浏览器控制台查看详细的连接日志