数字人对话WebSDK

产品能力

• 云渲染数字人

  • 云端渲染数字人是通过阿里云RTC提供视频流订阅，SDK在浏览器上拉取视频流呈现数字人的解决方案。

  • 云端渲染数字人具备完整的语音交互、脸部和肢体驱动能力，提供数字人多种对话模式和打断能力。

• 端渲染(端到端)数字人

  • 端渲染数字人是通过阿里云RTC提供音频和模型脸部肢体动作数据，SDK在浏览器上通过拉取数据并使用WebGL渲染数字人的解决方案。

  • 端渲染数据人同样具备完整的语音交互、脸部和肢体驱动能力，同样提供数字人多种对话模式和打断能力。

接入前须知

• 受浏览器底层WebSocket、底层录音权限、WebRTC等限制，本地开发环境仅支持使用localhost运行。生产环境上页面协议请使用HTTPS,否则会出现录音权限获取失败、拉流播放失败等问题。

• 云渲染数字人、端渲染数字人的语音交互模式分为两种模式：tap2talk模式 和 duplex双工模式

  • 在tap2talk模式下，SDK内部的语音服务会实时识别用户的语音输入。但是用户想打断数字人，需要通过额外事件来触发，比如点击屏幕，或者点击某按钮。

  • 在duplex双工模式下，SDK内部的语音服务会实时识别用户的语音输入。数字人在说话状态下，仍可以接受用户的语音打断信号。

    • 在duplex双工模式，容易受到外部环境音的影响导致触发频繁打断，请在相对安静的环境下使用双工模式。

• 若使用本文档提供的SDK，用于对公众提供人工智能生成合成服务，作为服务提供者需遵守《互联网信息服务深度合成管理规定》《人工智能生成合成内容标识办法》以及相关标准要求，履行人工智能生成合成内容标识的义务。

接入方法

示例工程

• 下载 vue版本 或 react版本 或 原生版本 的示例工程压缩包，解压到本地安装运行后，在页面中填入从服务端获取到的对话初始化参数即可启动对话

Npm集成

请根据自己使用的包管理器，选择对应的命令，安装lm-avatar-chat-sdk依赖包

当前版本是 0.0.5

npm i lm-avatar-chat-sdk

pnpm i lm-avatar-chat-sdk

yarn i lm-avatar-chat-sdk

设置挂载元素

云渲染数字人底层通过阿里云RTC进行音视频流的传输，需要挂载在一个video元素上。所以开发者要在页面html中先添加video容器元素。而端渲染数字人sdk会创建一个canvas用来渲染数字人画面，需要挂载在一个div元素上，所以页面中需要添加一个div容器元素。

// 云渲染
<video id="cloudAvatarContainer" muted></video>

// 端渲染
<div id="localAvatarContainer"></div>

创建对话数字人

对话数字人支持两种语音交互模式：tap2talk 和 duplex。这两种语音交互模式的取值可以通过SDK中的TYVoiceChatMode枚举值获取。云渲染和端渲染的创建方法相同，区别在于端渲染需要额外的资产信息，所以多了第三个入参

import {
  createAvatar,
  TYAvatarType,
  IAvatarInitConfig,
  TYVoiceChatMode,
  IAvatarAssetModelType
} from 'lm-avatar-chat-sdk';

const avatarInitParams = { // rtc相关参数需要从接口获取，详见IAvatarInitConfig
    rootContainer: 'xxx',
    appId: 'xxx',
    channel: 'xxx',
    timestamp: 'xxx',
    token: 'xxx',
    clientUserId: 'xxx',
    clientUserName: 'xxx',
    serverUserId: 'xxx',
    avatarUserId: 'xxx',
    sessionId: 'xxx',
} as IAvatarInitConfig 

const assetParams = { // 参数需要从接口获取，详见IAvatarAssetsConfig
  type: IAvatarAssetModelType.AVATAR_3D_TRADITIONAL,
  url: 'xxxx.zip?xxxx',
  secret: 'xxxxx',
  license: 'xxxxx'
}

// 创建云渲染数字人
const avatar = createAvatar(TYAvatarType.cloudAvatar, avatarInitParams)

// 创建端渲染数字人
const avatar = createAvatar(TYAvatarType.localAvatar, avatarInitParams, assetParams)

启动对话

avatar.start({
  mode: TYVoiceChatMode.tap2talk,
})

绑定回调

并不是所有回调都需要绑定，建议开发者根据业务开发需求进行绑定即可。

• onFirstFrameReceived

在数字人首页画面出现的时候触发此回调

avatar.onFirstFrameReceived(() => {
  console.log('数字人渲染完毕')
})

• onReadyToSpeech

在数字人可以开始进行语音交互的时候触发此回调

avatar.onReadyToSpeech(() => {
  console.log('可以进行语音交互了')
})

• onErrorReceived

在数字人内部出现错误的时候触发此回调, 更多错误码详情见此教程的错误码列表

avatar.onErrorReceived((err:TYError) => {
  console.log('数字人内部发生错误:' + err.code + ' ' + err.message)
})

• onStateChanged

在数字人内部状态发生变化的时候触发此回调，详情见SDK中的TYVoiceChatState类型声明。

云端数字人拥有三种状态：Listening(倾听)、Thinking(思考中)、Responding(反馈中)

// 数字人状态
avatar.onStateChanged((tyState: TYVoiceChatState) => {
  console.log('当前数字人状态' + tyState)
})

• onVolumeChanged

在数字人或者用户说话音量发生变化的时候触发此回调。回调返回的数据中，source为TYVolumeSourceType.mic的数据表示用户自己说话的音量，source为TYVolumeSourceType.player的数据表示数字人的音量。详情见SDK中的TYVolume和TYVolumeSourceType类型声明。

请注意：SDK已将数字人的音量做了归一化处理，数值大小范围为0～1

avatar.onVolumeChanged((data: TYVolume) => {
  if(data.source === TYVolumeSourceType.mic) {
    console.log('用户音量:' + data.volume)
  } else {
    console.log('数字人音量:' + data.volume)
  }
})

• onMessageReceived

在识别出数字人对话文本或用户对话文本的时候触发此回调，详情见SDK中的TYVoiceChatMessage和TYVoiceChatMessageType类型声明。

 avatar.onMessageReceived((msg: TYVoiceChatMessage) => {
  if(msg.type === TYVoiceChatMessageType.speaking) {
    console.log("用户的提问文本内容", msg.text)
  } else {
    console.log("数字人的回复文本内容", msg.text)
  }
})

• onPerformanceInfoTrack

数字人对话过程中性能相关的事件回调，如lm、tts的时延，rtc的音视频帧信息，详情见SDK中的TYPerformanceInfo 和 TYPerformanceInfoType 类型声明

  avatar.onPerformanceInfoTrack((info: TYPerformanceInfo) => {
    const { type, data } = info
    console.log('性能信息:', type, data)
  })

TYPerformanceInfo说明

当 type = TimestampStatistics时，data中包含了对话各链路的时延数据，具体如下：

当 type = RemoteRtcAudioStats 或 RemoteRtcVideoStats 时，返回的是rtc的音视频帧信息，由底层依赖的aliyun-rtc-sdk透出，字段信息说明参考https://developer.mozilla.org/en-US/docs/Web/API/RTCInboundRtpStreamStats

核心API

初始化创建

createAvatar(
  type: TYAvatarType,
  avatarInitParams: IAvatarInitConfig,
  assetParams?: IAvatarAssetsConfig,
)

参数说明

IAvatarInitConfig参数说明

IAvatarAssetsConfig参数说明，这是端渲染的必须字段，云渲染不需要

开启对话

 start(dialogParams: IDialogConfig)

IDialogConfig 参数说明

暂停收音/恢复收音

云端渲染数字人默认会自动开启收音。暂停收音和恢复收音功能均可以在三种语音交互模式下有效，但一般主要用于duplex双工语音交互场景。

在开启双工语音交互模式下，数字人容易受到外界环境音影响，开发者可以通过暂停收音的方法，让数字人免受外界环境音影响。

// true：暂停收音
// false（默认值）：恢复收音
avatar.muteLocalMic(mute: boolean)

打断

打断方法常用于tap2talk语音交互模式下，而在duplex双工模式下，SDK内部的语音服务本身就能识别用户新的语音输入进行打断。

avatar.interrupt()

文本问答

文本问答有两个常见使用场景，1.用户通过输入文本的形式向数字人进行提问，代替语音输入；2.用户需要指定数字人回复的内容。这两种场景的方法入参不同，详情见SDK中的 IRequestToRespondType 类型声明。

avatar.requestToRespond(type: IRequestToRespondType, content: string)

requestToRespond 参数说明

退出

在离开数字人页面或更换数字人角色的时候，都要调用此方法。否则会占用数字人服务并发数，页面中会存在多个数字人实例，导致异常情况出现。

avatar.exit()

错误码

应用内部错误

详细枚举值见SDK中的枚举值ApplicationErrorCode

RTC错误

详细枚举值见SDK中的枚举值RTCErrorCode

系统错误

详细枚举值见SDK中的枚举值SystemErrorCode

服务端错误

参考服务端错误码

URL协议限制

兼容性

• 目前SDK均不支持在原生的小程序开发上使用，但是可以尝试通过webview的方式打开自己的业务网页。开发者使用自己的业务网页时需要在域名根目录上添加小程序的校验文件，校验文件配置方案请参考各小程序平台的接入方式。

• 云渲染数字人和端渲染(端到端)数字人，底层均依赖阿里云RTC的能力。具体兼容性请参考：概述