npm package: @iwhalecloud-lab/metamee-digital-human-render
Description: MetaMee digital-human render
Author: adam24
Latest version: 1.0.12


# @iwhalecloud-lab/metamee-digital-human-render

## 数字人渲染组件

数字人实时渲染组件，支持实时视频流处理、绿幕抠像、流式音频驱动口型等功能，适用于数字人展示、智能问答等场景。


## 核心功能
- **WebRTC 实时通信**：通过 RTCPeerConnection 实现音视频流的接收与处理。
- **绿幕抠像**：基于 Seriously.js 的 chroma 效果，支持自定义绿幕颜色（默认绿色）。
- **流式音频驱动**：通过文本输入生成音频流，驱动数字人口型同步。
- **会话管理**：支持重复使用会话 ID（sessionid），避免资源泄漏。


## 安装
```bash
npm install @iwhalecloud-lab/metamee-digital-human-render
```

## 使用示例

### 1. HTML 结构
```html
<div id="digital-human-container"></div>
```

### 2. 初始化组件
```javascript
import { init, InitConfig, startHumanAudio } from '@iwhalecloud-lab/metamee-digital-human-render';

// 配置项
const config: InitConfig = {
  id: 'digital-human-container', // 挂载的 DOM 元素 ID
  url: 'your-rtc-service-url', // RTC 服务 URL
  avatarImageId: 123, // 形象 ID
  avatarImageUrl: 'placeholder-image.jpg', // 未拉流时的占位图
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }], // ICE 服务器（可选）,如rtc服务是ip，可以不设置iceServers，有一定概率会引起其他问题。
  width: 1080, // 展示宽度（可选，默认使用 挂载DOM 宽度）
  height: 1920, // 展示高度（可选，默认使用 挂载DOM 高度）
  options: {
    onSuccess: () => console.log('初始化成功'),
    onError: (errMsg) => console.error('初始化失败', errMsg),
  },
  tts_type: 'bytedance_stream_tts', // 语音合成类型（可选，默认值）
  bytedance_voice_type: 'voice-id-1', // 火山引擎 TTS 音色 ID（必填，当 tts_type 为 bytedance_stream_tts 时）
  sessionid: 12345678, //当前的会话ID，用于重复使用单路推流，当客户端传入sessionid时，会停止之前sessionid的连接，避免客户端异常断开时出现会话泄漏问题，如果不设置会默认生成一个
  
};

// 初始化
init(config);
```

### 3. 流式音频驱动（口型同步）
```javascript
const audioConfig = {
  url: 'your-audio-service-url', // 音频服务 URL
  text: '你好，我是数字人小鲸！', // 需要转换为音频的文本
  sessionid: 'existing-session-id', // 可选，重复使用会话 ID，和初始数字人使用的sessionid要保持一致
  lang_code: 'zh-CN', // 语言代码（可选，默认 en-US）
  type: 'echo', // 音频类型（可选，默认 echo）
  options: {
    onSuccess: () => console.log('音频驱动开始'),
    onError: (err) => console.error('音频驱动失败', err),
  },
};

startHumanAudio(audioConfig);
```

### 4. 流式音频驱动（口型同步）
```javascript
const audioConfig = {
  url: 'your-audio-service-url', // 音频服务 URL
  sessionid: 'existing-session-id', // 可选，重复使用会话 ID，和初始数字人使用的sessionid要保持一致
  options: {
    onError: (err) => console.error('音频驱动失败', err),
  },
};

abortHumanAudio(audioConfig);
```

### 5. 销毁组件（释放资源）
```javascript
// 在组件卸载或页面关闭时调用
destroy();
```


## 配置参数（InitConfig）

| 参数名          | 类型                          | 必填 | 默认值                     | 说明                                                                 |
|-----------------|-------------------------------|------|--------------------------|---------------------------------------------------------------------|
| id              | string                        | 是   | -                        | 挂载数字人渲染容器的 DOM 元素 ID                                      |
| url             | string                        | 是   | -                        | RTC 服务端 URL，用于建立 WebRTC 连接                                   |
| avatarImageId   | number                        | 是   | -                        | 数字人形象 ID（服务端所需参数）                                       |
| avatarImageUrl  | string                        | 否   | 空字符串                 | 未拉流成功时的占位图 URL，为空时显示空白                              |
| iceServers      | RTCIceServer[]                | 否   | []                       | WebRTC ICE 服务器配置（可选，用于 NAT 穿透）                           |
| width           | number                        | 否   | DOM 元素宽度            | 渲染容器宽度，未设置时自动获取挂载 DOM 的宽度                          |
| height          | number                        | 否   | DOM 元素高度            | 渲染容器高度，未设置时自动获取挂载 DOM 的高度                          |
| options         | Options                       | 否   | { onSuccess: () => {}, onError: () => {} } | 回调函数配置，包括初始化成功和错误处理                                |
| tts_type        | 'bytedance_stream_tts' \| 'hailuo_tts' | 否 | 'bytedance_stream_tts' | 语音合成类型（可选，当前支持火山引擎和海螺 TTS）                       |
| bytedance_voice_type | string | 否（当 tts_type 为 bytedance_stream_tts 时必填） | - | 火山引擎 TTS 音色 ID（对应 tts_type 为 bytedance_stream_tts 时必填）     |
| hailuo_tts_code | string | 否（当 tts_type 为 hailuo_tts 时必填） | - | 海螺 TTS 音色 ID（对应 tts_type 为 hailuo_tts 时必填）                 |
| sessionid       | number                        | 否   | 自动生成的会话 ID       | 重复使用的会话 ID，避免客户端异常断开时的会话泄漏                       |


## API 文档

### 1. `init(config: InitConfig): Promise<void>`
- **功能**：初始化数字人渲染组件，建立 WebRTC 连接并渲染视频流。
- **参数**：`config` - 初始化配置（见上表）。
- **返回值**：`Promise<void>`，成功时调用 `options.onSuccess`，失败时调用 `options.onError`。

### 2. `startHumanAudio(human: HumanConfig): Promise<Response>`
- **功能**：通过文本生成音频流，驱动数字人口型同步。
- **参数**：`human` - 音频配置对象，包含：
  - `url`: 音频服务端 URL（POST 请求地址）。
  - `text`: 需要转换为音频的文本内容。
  - `sessionid`: 可选，会话 ID（默认使用初始化时的 sessionid）。
  - `lang_code`: 语言代码（如 `zh-CN`、`en-US`，默认 `en-US`）。
  - `type`: 音频类型（默认 `echo`，具体含义由服务端定义）。
  - `options`: 回调函数配置（同初始化选项）。
- **返回值**：`Promise<Response>`，服务端返回的响应。
- **注意**：需在 WebRTC 连接状态为 `connected` 时调用，否则抛出错误。

### 3. `abortHumanAudio(abortHuman: AbortHumanConfig): Promise<Response>`
- **功能**：中止文本生成音频流。
- **参数**：`abortHuman` - 音频配置对象，包含：
  - `url`: 音频服务端 URL（POST 请求地址）。
  - `sessionid`: 可选，会话 ID（默认使用初始化时的 sessionid）。
  - `options`: 回调函数配置（同初始化选项）。
- **返回值**：`Promise<Response>`，服务端返回的响应。
- **注意**：需在 WebRTC 连接状态为 `connected` 时调用，否则抛出错误。

### 4. `destroy(): void`
- **功能**：销毁组件，释放 WebRTC 连接和渲染资源，避免内存泄漏。
- **调用时机**：组件卸载或页面关闭时（建议监听 `beforeunload` 事件）。


## 注意事项
1. **浏览器兼容性**：需支持 WebRTC 和 Canvas 的现代浏览器（如 Chrome、Firefox、Edge 等）。
2. **会话管理**：重复调用 `init` 时，传入相同 `sessionid` 会断开前一次连接，避免多会话冲突。
3. **资源释放**：务必在组件卸载时调用 `destroy()`，否则可能导致内存泄漏或端口占用。
4. **网络要求**：ICE 服务器配置需根据实际网络环境调整，确保 WebRTC 连接稳定。



## 联系我们
- **官网**：https://lab.iwhalecloud.com