# 硅基DUIX H5 SDK使用文档

# 安装

# Install Duix
npm i duix-guiji -S

# 快速开始

Demo 请点这里 (opens new window)

您也可以在 CodePen (opens new window) 中体验

import DUIX from 'duix-guiji'
const duix = new DUIX({
    containerLable: '.remote-container',
    sign: 'xxxxxxxxx'
})

注意： Vue2的双向数据绑定机制会破坏我们内部使用的事件绑定机制，不要将duix实例放在Vue2的data中。如下：

import DUIX from 'duix-guiji'

export default {
      name: 'Home',
      data: function () {
            return {
                // duix: null 这一行不能有
            }
      },
      methods: {
            initDUIX() {
              this.duix = new DUIX({
                containerLable: '.container',
                sign: 'xxxx',
              })
            },
      },
      mounted() {
            this.initDUIX()
      }
}

如何获取sign? (opens new window)

# 选项

以上示例中的new DUIX(options)即可得到一个DUIX实例，其中option是一个配置对象，细节如下：

名称 类型 描述 默认值 示例
containerLable string 数字人容器。数字人将渲染到这个Dom中。 .remote-container #human
sign string duix sign，用于鉴权。另见：如何获取sign? (opens new window)

# 方法

# start(option:object): string

new DUIX(option) 只创建了一个DUIX对像，此时界面上并不会显示数字人，调用 start 方法将开始渲染。

注意： 此方法需要在intialSucccess事件触发后调用，intialSucccess事件表示所有资源准备完成。如下：

duix.on('intialSucccess', () => {
  const sessionId = duix.start({
     robotMode: 'bot',
     muted: true,
     transparent: false,
     wipeGreen: false,
 })
 console.log('sessionId', sessionId)
})

参数

key 类型 必填 默认值 说明
robotMode string 否 'null' 开启一次会话。 robotMode参数指定以何种模式开启duix，可选值'bot'。
null：直驱模式。调用 speak 方法后，数字人将直接说出这句话。比如：调用 speak('你是谁?') ，数字人会说“你是谁？”
bot：对话模式。调用 speak 方法后，数字人将回答出您的问题。比如：调用 speak('你是谁？') ，数字人可能会说“我是硅基数字人爱夏，很高兴认识你。”
muted boolean 否 false 是否以静音的模式开启数字人视频。
重要提示: 由于自动播放政策 (opens new window)限制，如果您的网页还没有与用户有任何点击交互，请把这个参数置为true，否则将导致数字人无法加载。如果您有这样的需求，建议您先用静音模式启动，在产品中设计一个交互，比如一个“开始”的按钮来调用duix.setVideoMuted(false)
openAsr boolean 否 false 是否直接开启实时识别，此项传true，相当于在调start后立即调用 openAsr 方法
wipeGreen boolean 否 false 是否对视频做扣绿幕操作。在平台上创建会话时不选背景，背景将默认是一个标准绿幕，搭配这个属性，可以实现背景透明的效果。
transparent boolean 否 false 数字人背景是否透明。此选项效果与wipeGreen效果类似，作为扣绿幕效果不理想时的备选方案。此方案消耗更多的性能，可能导致数字人卡顿、掉帧。

返回值 本次会话的ID，可用于从后端主动关闭此会话。

# setVideoMuted(flag:boolean)

设置数字人视频是否静音, true是静音，false为非静音。

# speak(content: string, [option: Object])

驱动数字人说话，支持文本驱动和音频文件驱动。 第二个参数是可选的，如果需要使用音频文件驱动，可以如下传参。

duix.speak('xx',{wavPath: 'https://your.website.com/xxx/x.wav'})

# break()

立即停止数字人说话

# startRecord()

开始录音。

# stopRecord()

结束录音，录音成功后将返加语音识别结果（文本），返回Promise。

# openAsr()

开启语音实时识别(注意此方法需在show触发时候调用)。开启语音实时识别后，可通过监听 asrResult 事件，接收识别（文本）结果。

# closeAsr()

关闭语音实时识别。

# stop()

停止当前会话。建议在页卸载事件中调用此方法，以防止刷新或关闭网页时当前会话不释放造成下次打开时触发busy事件。

window.addEventListener('beforeunload', function(event) {
    if (duix) {
     duix.stop()
    }
});

# on(eventname, callback)

监听事件。

# 参数
# eventname

事件名称，详见下方表格。

# callback

回调函数

# getLocalStream()

获取本地语音流，方便外部做音频可视化等功能

# getRemoteStream()

获取远端音视频流，方便外部做自定义

# 事件

名称 描述
error 有未捕获错误时触发。
bye 会话结束时触发。
intialSucccess 数字人初始化成功。可以在这个事件的回调中调用start方法
show 出数字人已显示。
progress 数字人加载进度。
command 服务端驱动数字人的命令。如果调用 start 时指定对话模式，每次服务端执行的话术回复都会通过该事件触发，里面包含本轮数字人回复的文本等信息，可以用来做字幕。
speakStart 驱动数字人说话，到数字人实际说话之间有一点延迟，此事件表示数字人实际开始说话了
speakEnd 数字人说话结束
openAsrSuccess 语音实时识别开启成功后触发
asrResult 语音实时识别结果
asrClose 关闭语音实时识别成功时触发
report 每秒报告RTC网络/画面质量等信息

# report 事件数据说明

{
    "video": { // 视频相关信息
        "download": {
            "frameWidth": 1920, // 分辨率-宽
            "frameHeight": 1080,// 分辨率-高
            "framesPerSecond": 24,// 分辨率-帧率
            "packetsLost": 0, // 总丢包数
            "packetsLostPerSecond": 0 // 总丢率（每秒丢包数）
        }
    },
    "connection": { // 连接信息
        "bytesSent": 206482, // 发送总字节数
        "bytesReceived": 79179770, // 接收总字节数
        "currentRoundTripTime": 3, // 包往返时间（单位毫秒），这个时间越大画面越延迟
        "timestamp": 1688043940523,
        "receivedBitsPerSecond": 2978472, // 接收码率（每秒接收到的bit数，1Mb = 1024^2 bit）
        "sentBitsPerSecond": 7920 // 发送码率（每秒发送的bit数，1Mb = 1024^2 bit）
    }
}

# 版本记录

1.1.21

  1. 修复扣绿幕相关的一个Bug

1.1.19

  1. 修复report事件在初次触发时参数可能不完整的问题 1.1.18

  2. speakStart和speakEnd事件暴露与本次事件相关的额外数据。

1.1.17

  1. 新增report事件。

1.1.15

  1. 优化绿幕扣图算法，效果更好，性能消耗更低。
  2. 绿幕扣图与背景透明同时打开时，只启用绿幕扣图，以节省客户端GPU消耗。
  3. 其他性能优化。

1.1.14

  1. 面页刷新/关闭时自动释放资源。

1.1.13

  1. 修复一些问题。

1.1.11

  1. duix.stop方法关闭ws通道。

1.1.10

  1. 修复文档中的一处错误。

1.1.8

  1. 更新README文档，增加start方法调用注意事项说明。

1.1.6

  1. 新增break（打断）方法，可立即停止数字人说话。

1.1.5

  1. start方法新增参数wipeGreen，以支持对视频扣绿幕。

1.1.4

  1. 修复当指定的数字人容器没有设置z-index时，数字人可以挡住UI的问题。
  2. 优化stop方法，使得在页面卸载类事件中调用stop方法可以确保后端释放资源。比如：
window.addEventListener('beforeunload', function(event) {
    console.log('on beforeunload')
    if (duix) {
        duix.stop()
    }
});
  1. 优化数字人显示策略，数字人画面将在show事件触发时才会显示。

1.1.2

  1. 启动时打印版本号，方便定位问题。
  2. start 方法的参数新增transparent值，如果传true，则数字人背景透明。
  3. start 方法将返回一个uuid，此UUID是本次会话的ID，可用于从后端主动关闭此会话

1.1.1

  1. 修复start方法中传muted: true无效的bug。

1.1.0

  1. openAsr方法不再传入回调方法，改用 asrResult 事件来接收实时语音识别回传的识别结果。
  2. 新增 speakStart 事件，表示数字人开始说话。
  3. 新增 speakEnd 事件，数字人说话结束。
  4. stopRecord 方法新增支持 Promise 方式调用，原传回调的方式目前依然兼容，建议使用 Promise 方式。

1.0.30

  1. 更改DUIX构造函数，现在只需两个必传参数。
  2. 增强了IOS兼容性，修复IOS15.1以上实时识别换效的问题。
  3. 新增统一日志。
  4. start方法接收robotMode参数，现在可以在不重新new实例的情况下，切换对话/直驱模式。

1.0.27

  1. 修复rtc回音问题

1.0.26

  1. 取消sdk内部录音后，自动播放功能，改为事件抛出，外部播放

1.0.25

  1. 取消sdk内部语音转文字后自动播放功能，改为事件抛出，外部播放

1.0.24

  1. 新增私有化配置支持

1.0.23

  1. 一键构建打包脚本优化

1.0.22

  1. 新增xmpp新增disconnect外抛时间
  2. rtc audio参数新增几个配置项

1.0.19

  1. 更改sdk底层架构，改为走webrtc模式

0.0.45 (暂未发布到npm)

  1. 解决监听息屏事件多次触发的问题
  2. 解决数字人pause后stop后resume人脸会继续播放的问题
  3. 解决数字人stop后resume音频会继续播放的问题
  4. 解决在暂停播放情况下 切到后台再回来会直接开始播放

0.0.44

  1. 大版本添加鉴权功能
  2. 优化测试代码方便测试
  3. 优化了一些bug

0.0.43

  1. 新增从AudioContext获取MediaStream的方法getAudioDest

0.0.42

  1. Request.js => getArrayBuffer 添加主动断开请求的方法
  2. DigitalHuman.js => _sayVoice 添加判断网络取消时的return
  3. DigitalHuman.js => stop 添加cancel方法 防止stop后网络请求才成功导致stop失败

0.0.41

  1. Request.js 添加axios超时时间
  2. Request.js => getArrayBuffer 添加音频请求失败返回 && DigitalHuman.js => _sayVoice 添加判断 音频请求失败时调用event && DUIX.js => 添加新的事件 audioFailed 音频请求失败时event

0.0.40

  1. 修复bug DigitalHuman.js line:166 & 169 事件名错误导致wsClose wsError不触发的bug
  2. 修改webpack配置 默认输出一次sdk版本 方便开发和生产环境的调试

0.0.39

  1. 新增暂停(pause)，恢复(resume)方法。
  2. 修复偶现的吞字现象。
  3. 播放结束不再触发puase事件，只触发ended 事件。
  4. 新增功能，页面不可见时暂停画面和声音，恢复可见时继续播放。

0.0.38

  1. 修复偶现的调用say方法后，加载卡住，不能播放的bug。
  2. 新增功能。当options.body.autoplay=false时，调用say不自动播放静默。

0.0.37

  1. 新增 getCanvas() 方法。
  2. 新增 getAudioContext() 方法。

0.0.36

  1. 修改启动方式,现在以ip形式系统 手机上可以正常访问测试
  2. AIFace.js reconnectInterval修改为1 开启断线重连
  3. Bug修复 AIFace.js line:48 close => onClose

0.0.34

  1. 新增 wsClose 事件，AIFace 连接关闭事件。
  2. 新增 wsError 事件, AIFace 连接错误事件。

0.0.33

  1. 静默视频正放/倒放切换，解决静默首尾不相接（如约旦男）时静默视频跳动的问题。
  2. 删除一些调试日志。
  3. 修复不触发load事件的bug

0.0.32

  1. 修复过短的音频不能触发 canplaythrough 事件的bug。

0.0.31

  1. 进一步优化客户端缓冲策略，降低内存占用，现在约旦模型内存占用稳定在700M左右。
  2. 修复一些bug

0.0.30

  1. 修改客户端缓冲策略，降低客户端内存占用。
  2. 新增配置 options.body.autoplay ，用于控制静默视频加载完是否自动播放。默认为true，如置为false，可在 bodyload 事件触发后调用 duix.playSilence() 方法主动播放。
  3. 优化TTS缓存方案，现在缓存可以保留更长时间。

0.0.27

  1. 新增配置body.autoplay控制身体加载完后是否自动播放。
  2. 删除实时贴图的代码，必须走缓冲，缓冲大小可设置为0。
  3. 默认缓冲策略修改为auto，由第一次加载人脸的开始半秒加载速度预测缓冲大小。
  4. 调整解码间隔时间，降低CPU的瞬间消耗，解决部分手机CPU瞬间占用过高导致页面强行刷新的问题。

0.0.26

  1. 修复不传 quality.fps 和 quality.quarter时的报错。
  2. 新增bodyprocess事件用于通知身体加载进度。

# 相关协议

# 人工智能生成合成内容标识规范

（1）我们将依据相关法律法规，对人工智能生成合成内容添加相应标识（如在生成合成内容或者交互场景界面中添加的显式标识，采用技术措施在生成合成内容的文件元数据中添加的隐式标识）。您应确保您已仔细阅读并理解《人工智能生成合成内容标识办法》及其他相关的标识管理要求。您不得使用或尝试使用任何技术手段或其他方法删除、篡改、伪造、隐匿该等生成合成内容标识，不得为他人实施删除、篡改、伪造、隐匿该等生成合成内容标识行为提供工具或者服务，不得通过不正当标识手段损害他人合法权益。
（2）在特定场景下，为更好地满足您的使用需求，我们可能根据您的申请为您提供没有添加显式标识的人工智能生成合成内容。如您申请我们提供没有添加显式标识的生成合成内容的，您需承诺并保证：
①不利用该内容发布、传播任何虚假信息或从事其他任何违法违规活动；
②在发布或传播基于深度学习、虚拟现实、深度合成、生成式人工智能等新技术制作的非真实信息，或其他可能引发公众误解或混淆的信息内容时，应当以显著方式标识；
③在向第三方分享该内容或使用网络信息内容传播服务发布该内容或以其他方式使用该内容时，主动声明其为人工智能生成合成内容；
④遵守其他相关法律、法规、政策、办法的规定。
（3）如您违反上述约定，您应自行承担由此引起的所有责任，并赔偿由此给我们及第三方造成的全部损失（包括但不限于直接损失、间接损失、诉讼费、仲裁费、公证费、鉴定费、律师费、差旅费、保全费用、保全保险费、向任何第三方承担的责任、行政处罚、罚款等）。