@iwhalecloud-lab/metamee-digital-human-render

数字人渲染组件

数字人实时渲染组件，支持实时视频流处理、绿幕抠像、流式音频驱动口型等功能，适用于数字人展示、智能问答等场景。

核心功能

• WebRTC 实时通信：通过 RTCPeerConnection 实现音视频流的接收与处理。
• 绿幕抠像：基于 Seriously.js 的 chroma 效果，支持自定义绿幕颜色（默认绿色）。
• 流式音频驱动：通过文本输入生成音频流，驱动数字人口型同步。
• 会话管理：支持重复使用会话 ID（sessionid），避免资源泄漏。

安装

npm install @iwhalecloud-lab/metamee-digital-human-render

使用示例

1. HTML 结构

<div id="digital-human-container"></div>

2. 初始化组件

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. 流式音频驱动（口型同步）

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. 销毁组件（释放资源）

// 在组件卸载或页面关闭时调用
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. destroy(): void

• 功能：销毁组件，释放 WebRTC 连接和渲染资源，避免内存泄漏。
• 调用时机：组件卸载或页面关闭时（建议监听 beforeunload 事件）。

注意事项

1. 浏览器兼容性：需支持 WebRTC 和 Canvas 的现代浏览器（如 Chrome、Firefox、Edge 等）。
2. 会话管理：重复调用 init 时，传入相同 sessionid 会断开前一次连接，避免多会话冲突。
3. 资源释放：务必在组件卸载时调用 destroy()，否则可能导致内存泄漏或端口占用。
4. 网络要求：ICE 服务器配置需根据实际网络环境调整，确保 WebRTC 连接稳定。

联系我们

• 官网：https://lab.iwhalecloud.com