数字人流媒体服务WebSDK

接入前须知

1. aliyun-avatar-sdk本身仅运行在浏览器环境，不包含操作服务端实例的接口（如启动数字人、结束数字人、播报文本等功能），如有需要请参考OpenAPI文档。同时，您可以在demo合集中的public_demo文件夹找到一个简易的nodejs服务端工程，帮助您快捷体验数字人流媒体服务，具体操作请参考public_demo文件夹下的readme.md；

2. 页面协议请使用HTTPS，否则在部分机型上会出现录音权限被拒绝，拉流播放失败等问题；

3. 由于网络等原因导致im连接中断（错误码：15011002）时，连接断开期间本地录音将不会保留；

4. 各平台浏览器兼容性测试详见文末附录各平台浏览器兼容性；

5. 如在使用过程中遇到其他问题，请先浏览常见问题排查，如问题仍然存在，请提交工单与我们联系；

接入方法

npm引入

可以通过npm安装：

$ # save into package.json dependencies with -S
$ npm install aliyun-avatar-sdk -S

CDN引入

若通过npm引入aliyun-avatar-sdk出现本地调试正常，打包到线上环境异常的情况，请尝试将aliyun-avatar-sdk从package.json中的dependencies中移除，采用CDN引入的方式。

<script src="https://g.alicdn.com/code/npm/@alife/aliyun-avatar-sdk/1.0.19/index.js"></script>

CDN方式引入的SDK无法通过ES Module语法引入，而是将SDK实例挂载到window上，以DialogAvatarSDK为例：

/*
 * CDN方式 引入DialogAvatarSDK
 */
/* global options */
const dialogAvatarSDK = new window.DialogAvatarSDK({ options });

离线引入

从OSS下载SDK包

$ # 切换到项目根目录
$ cd your-project
$ # 解压下载的压缩包
$ tar -xvf avatar-sdk.tar.gz
$ # 本地安装
$ npm install avatar-sdk

功能模块展示

demo使用

demo下载

有两种方式下载demo：

1. 从OSS下载DEMO合集，解压；

2. 或通过npm安装aliyun-avatar-sdk后，在包根目录下的demos文件夹中找到相应demo；

demo 介绍

解压后的demo文件结构如下：

├── asr_demo # 自定义问答（第三方问答机器人）
│ ├── readme.md # 自定义问答demo的说明文件
│ ├── src
│ │ ├── client.ts
│ │ ├── server.ts # nodejs 后端工程入口文件
│ │ └── www # 前端项目
│ │ ├── index.html
├── public_demo
│ ├── readme.md # 公有云demo的说明文件
│ ├── src
│ │ ├── client.ts
│ │ ├── server.ts #nodejs 后端工程入口文件
│ │ └── www # 前端项目
│ │ ├── broadcastingAvatar.html # 播报数字人（资讯播报）
│ │ ├── dialogAvatar.html # 互动数字人（客服助理）
├── readme.md # demo总说明文件
├── private_demo # 公有云用户忽略

您可以根据需要选择使用以下demo快速体验数字人：

• 播报数字人（资讯播报）：用户输入文字，由数字人播报出来；

• 互动数字人（客服助理）：用户通过文字/语音和数字人对话，数字人的回答内容由阿里云智能对话机器人生成（需要您在数字人开放平台配置对话机器人）

• 用户自定义问答机器人：适合配置第三方问答机器人（如：通义千问、文心一言、ChatGPT等）。您可以在Web端通过ASR（自动语音识别）获取识别结果，将识别文字传给您的问答机器人，再将回答文本传输给数字人播报。注意：需要您开通阿里云智能语音交互服务，以及第三方对话接口。

使用方法

1. 运行nodejs服务端工程

# 生成ssl证书（仅测试用，请勿用于生产环境）
openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem
# ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET 的获取请参考https://help.aliyun.com/zh/tablestore/support/obtain-an-accesskey-pair
npm install --registry=https://registry.npmmirror.com && npm run build && ALIBABA_CLOUD_ACCESS_KEY_ID=******** ALIBABA_CLOUD_ACCESS_KEY_SECRET=******** node ./dist/server.js

2. 运行前端工程

# cd到前端项目的根目录
cd ./src/www
# copy ssl证书
cp ../../cert.pem ./
cp ../../key.pem ./
# 安装http-server
npm install -g http-server
# 启动本项目
http-server -S -C cert.pem -p 3001

3. 访问demo页

在启动了服务端和前端工程后：

访问https://127.0.0.1:3001/dialogAvatar.html 互动数字人DEMO

访问https://127.0.0.1:3001/broadcastingAvatar.html 播报数字人DEMO

互动数字人 - DialogAvatarSDK

快速入门代码示例

/*
 * 引入DialogAvatarSDK
 */
import { DialogAvatarSDK } from 'aliyun-avatar-sdk';

/*
 * 获取建立im和拉rtc流的关键信息
 */
// StartInstanceRes：从服务端StartInstance接口返回值
/* global StartInstanceRes */
const { sessionId, token, channel } = StartInstanceRes;

/*
 * 调用构造方法，输入服务端返回的信息
 */
const dialogAvatarSDK = new DialogAvatarSDK({
  // im连接参数
  tenantId: "", // 用户自行提供
  appId: "", // 用户自行提供
  sessionId,
  token, // 注意是StartInstance外层返回的token，不是channel里的token
  // rtc拉流相关参数
  /*
  * 注意StartInstance接口返回的channel中的变量为大驼峰，如果服务端没有转化的话
  * 前端需要在这里手动转成小驼峰
  */
  channel: {
    appId: channel.AppId, // 手动转成小驼峰
    channelId: channel.ChannelId,
    expiredTime: channel.ExpiredTime,
    gslb: channel.Gslb,
    nonce: channel.Nonce,
    token: channel.Token,
    type: channel.Type,
    userId: channel.UserId,
  },
  // 用来播放rtc下行流的容器
  videoDOM: document.getElementById("rtc"),
  // 选项
  options: {
    wsUrl: "wss://avatar-im.console.aliyun.com/ws", // 建立IM连接的websocket地址
    maxReconnectTimeout: 300000, // 断线重连最大尝试时间(ms)，超出这个时间仍未重连成功将抛出断线重连超时错误
    audio: {
      autoStartRecord: false, // 是否在初始化过程中自动开启浏览器录音
      interval: 100, // 音频采集间隔(ms)，注意不能小于60ms，不能大于1000ms，否则会抛出错误
      autoDodge: false, // 是否开启音频闪避
    },
    rtc: {
      muted: false, // 是否静音订阅流
      // chromaKey: DialogAvatarSDK.canUseChromaKey(), // 如果需要开启抠绿幕，请解注释这行代码
    },
  },
  // 初始化成功回调
  onInitSuccess: () => {
    console.log("IM连接成功，RTC拉流成功");
    console.log(dialogAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
  },
  // RTC初始化成功回调
  onRtcInitSuccess: () => {
    console.log("RTC拉流成功，等待IM链接...");
    console.log(dialogAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
  },
  // IM初始化成功回调
  onIMInitSuccess: () => {
    console.log("IM连接成功，等待RTC拉流...");
  },
  // 错误回调
  onError: (e) => {
    console.error(e);
  },
  // 警告回调
  onWarning: (msg) => {
    console.warn(msg);
  },
  // 收音开始回调
  onRecordingStart: () => {
    // 可以在ui上提示用户
  },
  // 收音结束回调
  onRecordingStop: () => {
    // 可以在ui上提示用户
  },
  // ASR下发文本回调
  onASR: (text, sentenceId) => {
    console.log(`ASR: ${text}`);
    console.log(`sentenceId: ${sentenceId}`);
  },
  // 数字人回答下发文本回调
  onAnswer: (text, sentenceId) => {
    console.log(`Answer: ${text}`);
    console.log(`sentenceId: ${sentenceId}`);
  },
  // 未知im消息回调，用于接收后端业务增加新的消息类型
  onUnknownIMMessage: (msg) => {
    console.log("onUnknownIMMessage", msg);
  },
});

/*
 * 初始化
 */
dialogAvatarSDK
  .init()
  .then(() => {
    // 等同于onInitSuccess
    console.log("IM连接成功，RTC拉流成功");
    // dialogAvatarSDK.openAutoDodge(); // 开启音频闪避
    // dialogAvatarSDK.stopRecording(); // 手动停止收音，会触发onRecordingStop
    dialogAvatarSDK.startRecording().then(() => {
      // 手动开启收音，会触发onRecordingStart
      console.log("录音成功");
    });
    dialogAvatarSDK.sendText('查询杭州天气');
    // dialogAvatarSDK.destroy(); // 销毁实例
  })
  .catch((e) => {
    // 同样的错误也会被onError捕获
    console.log(e);
  });

新建实例

构造函数入参如下表：

绑定回调

除了在构造函数绑定监听回调外，还可以直接在实例上绑定监听回调；

• onInitSuccess 初始化成功回调

表示RTC和IM通道初始化均完成，可以与数字人正常进行对话，在onIMInitSuccess和onRtcInitSuccess之后触发

/* global dialogAvatarSDK */
dialogAvatarSDK.onInitSuccess = () => {
  console.log("IM连接成功，RTC拉流成功");
  console.log(dialogAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
};

• onIMInitSuccess IM初始化成功回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onIMInitSuccess = () => {
  console.log("IM连接成功，等待RTC拉流...");
};

• onRtcInitSuccess RTC初始化成功回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onRtcInitSuccess = () => {
  console.log("RTC拉流成功，等待IM链接...");
  console.log(dialogAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
};

• onError/onWarning 错误/警告回调

/* 不推荐 */
/* global dialogAvatarSDK */
dialogAvatarSDK.onError = (e) => {
  console.error(`errorCode: ${e.errorCode}, source:${e.source}, errorMsg:${e.errorMsg}`);
};

dialogAvatarSDK.onWarning = (e) => {
  console.warn(`errorCode: ${e.errorCode}, source:${e.source}, errorMsg:${e.errorMsg}`);
};

回调入参e数据结构：

• onASR ASR下发文本回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onASR = (text, sentenceId) => {
  console.log(`ASR Result: ${text}`);
  console.log(`sentenceId: ${sentenceId}`);
};

回调入参说明：

• onAnswer 数字人回答下发文本回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onAnswer = (text, sentenceId) => {
  console.log(`Answer: ${text}`);
  console.log(`sentenceId: ${sentenceId}`);
};

回调入参说明：

• onRecordingStart 收音开始回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onRecordingStart = () => {
  // 可以在ui上提示用户开始收音
};

• onRecordingStop 收音结束回调

/* global dialogAvatarSDK */
dialogAvatarSDK.onRecordingStop = () => {
  // 可以在ui上提示用户停止收音
};

初始化

初始核心流程：

1. 建立im连接;

2. rtc拉流；

3. 开启浏览器录音并通过im发送；（当options.autoStartRecord为true时）

• init 初始化回调

/* global dialogAvatarSDK */
dialogAvatarSDK.init().then(
  () => {
    // 等同于onInitSuccess
    console.log("IM连接成功，rtc拉流成功");
  },
).catch(
  (e) => {
    // 该错误也会被onError捕获
    console.error(e);
  },
);

暂停/开始收音

/* global dialogAvatarSDK */
dialogAvatarSDK.stopRecording(); // 手动停止收音/自定义音频采集，会触发onRecordingStop
dialogAvatarSDK.startRecording().then(() => {
  // 手动开启收音/自定义音频采集，会触发onRecordingStart
  console.log("录音成功");
});

文字互动

除了使用麦克风收音外，您还可以使用文本与数字人进行对话互动

/* global dialogAvatarSDK */
dialogAvatarSDK.sendText('查询杭州天气');

RTC静音/取消静音

/* global dialogAvatarSDK */
dialogAvatarSDK.muteRtc();
dialogAvatarSDK.unMuteRtc();

透明背景

在启动数字人实例时若选择开启了透明通道，可以将数字人背景透明化，透出自定义背景及可交互组件，如按钮等。

以下为实现透明背景的参考代码，透明背景开关需要在SDK实例化前配置：

/* global DialogAvatarSDK */
// DialogAvatarSDK的入参
const params = {};
// 按照“新建实例”的要求填写params中的参数
// ...
// 打开透明背景功能
params.options.rtc.chromaKey = DialogAvatarSDK.canUseChromaKey();
// 实例化SDK
const dialogAvatarSDK = new DialogAvatarSDK(params);

高级功能

• 暴露阿里云RTC原始对象

/* global dialogAvatarSDK */
// 访问aliyun-webrtc 原始对象
console.log(dialogAvatarSDK.rtc.aliRtcEngine);

• 暴露Websocket原始对象

/* global dialogAvatarSDK */
// 访问WebSocket 原始对象
console.log(dialogAvatarSDK.websocket);

• 音频闪避

音频闪避的含义为：当数字人说话时，暂停浏览器收音。

音频闪避有两种开启方式：

1. 自动开启：

如果构造函数的options.audio.autoDodge字段设置为true，则会自动开启

2. 手动开启：

/*
* 执行构造函数后，手动开启/关闭音频闪避
*/
/* global dialogAvatarSDK */
dialogAvatarSDK.openAutoDodge();
dialogAvatarSDK.closeAutoDodge();

销毁实例

断开rtc拉流、im连接、停止录音，避免资源浪费；

dialogAvatarSDK.destroy();

播报数字人 - BroadcastingAvatarSDK

快速入门代码示例

import { BroadcastingAvatarSDK } from 'aliyun-avatar-sdk';
/*
 * 获取建立im和拉rtc流的关键信息
 */
// StartInstanceRes：从服务端StartInstance接口返回值
/* global StartInstanceRes */
const { channel } = StartInstanceRes;

/*
 * 调用构造方法，输入服务端返回的信息
 */
const broadcastingAvatarSDK = new BroadcastingAvatarSDK({
  // rtc拉流相关参数
  /*
  * 注意StartInstance接口返回的channel中的变量为大驼峰，如果服务端没有转化的话
  * 前端需要在这里手动转成小驼峰
  */
  channel: {
    appId: channel.AppId, // 手动转成小驼峰
    channelId: channel.ChannelId,
    expiredTime: channel.ExpiredTime,
    gslb: channel.Gslb,
    nonce: channel.Nonce,
    token: channel.Token,
    type: channel.Type,
    userId: channel.UserId,
  },
  // 用来播放rtc下行流的容器
  videoDOM: document.getElementById("rtc"),
  options: {
    maxReconnectTimeout: 300000, // 断线重连最大尝试时间(ms)，超出这个时间仍未重连成功将抛出断线重连超时错误
    rtc: {
      muted: false, // 是否静音订阅流
      // chromaKey: BroadcastingAvatarSDK.canUseChromaKey(), // 如果需要开启透明背景，请解注释这行代码
    },
  },
  // 初始化成功回调
  onInitSuccess: () => {
    console.log("RTC拉流成功");
  },
  // 错误回调
  onError: (e) => {
    console.error(e);
  },
  onWarning: (msg) => {
    console.warn(msg);
  },
});

/*
 * 初始化
 */
broadcastingAvatarSDK
  .init()
  .then(() => {
    // 等同于onInitSuccess
    console.log("RTC拉流成功");
    console.log(broadcastingAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
  })
  .catch((e) => {
    // 同样的错误也会被onError捕获
    console.log(e);
  });

// broadcastingAvatarSDK.destroy(); // 销毁实例

新建实例

构造函数入参

绑定回调

除了在构造函数绑定监听回调外，还可以直接在实例上绑定监听回调；

• onInitSuccess 初始化成功回调

/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.onInitSuccess = () => {
  console.log("RTC拉流成功");
  console.log(broadcastingAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
};

• onError/onWarning 错误/警告回调

/* 不推荐 */
/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.onError = (e) => {
  console.error(`errorCode: ${e.errorCode}, source:${e.source}, errorMsg:${e.errorMsg}`);
};

broadcastingAvatarSDK.onWarning = (e) => {
  console.warn(`errorCode: ${e.errorCode}, source:${e.source}, errorMsg:${e.errorMsg}`);
};

回调入参e数据结构：

初始化

初始化核心流程：rtc拉流

/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.init().then(
  () => {
    // 等同于onInitSuccess
    console.log("RTC拉流成功");
    console.log(broadcastingAvatarSDK.rtc.aliRtcEngine); // 此时可以访问aliRtcEngine原始对象
  },
).catch(
  (e) => {
    // 该错误也会被onError捕获
    console.error(e);
  },
);

RTC静音/取消静音

/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.muteRtc();
broadcastingAvatarSDK.unMuteRtc();

透明背景

在启动数字人实例时若选择开启了透明通道，可以将数字人背景透明化，透出自定义背景及可交互组件，如按钮等。

以下为实现透明背景的参考代码，透明背景开关需要在SDK实例化前配置：

/* global BroadcastingAvatarSDK */
// BroadcastingAvatarSDK的入参
const params = {};
// 按照“新建实例”的要求填写params中的参数
// ...
// 打开透明背景功能
params.options.rtc.chromaKey = BroadcastingAvatarSDK.canUseChromaKey();
// 实例化SDK
const broadcastingAvatarSDK = new BroadcastingAvatarSDK(params);

高级功能

• 暴露阿里云RTC原始对象

/* global broadcastingAvatarSDK */
console.log(broadcastingAvatarSDK.rtc.aliRtcEngine); // 访问aliyun-webrtc 原始对象

销毁实例

断开rtc拉流，避免资源浪费；

/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.destroy();

常见问题

录音失败

当在接入了aliyun-avatar-sdk的页面第一次录音时，系统会弹窗提醒是否开启录音权限（不同浏览器的弹窗提示可能会有所差异），如果在同意开启录音权限后仍然无法录音，或没有弹出开启录音权限的弹窗，请按照以下步骤排查问题：

PC端：

1. 检查协议名是否为https，例如https://www.aliyun.com/

2. 请点击浏览器地址栏下的锁按钮，查看是否在该页面开启了录音权限

移动端H5：

1. 纯H5页面在部分APP中无法获取录音权限，例如手机淘宝APP，微信等，aliyun-avatar-sdk暂不支持在这些APP中的录音功能，如有Native APP拉流需要请参考数字人流媒体服务AndroidSDK;

2. 检查协议名是否为https，例如https://www.aliyun.com/。部分手机浏览器会拒绝在http协议下调用录音权限；

如果问题仍然存在，请提交工单与我们联系。

画面没有声音/无法自动播放

由于chrome对自动播放的限制，禁止自动播放带音频轨道的视频，如果您的页面在没有任何用户操作的情况下自动拉流（例如用js触发的方式自动拉流），会出现数字人无声音的问题，或浏览器控制台报错如下，无法播放拉流视频。

这种情况有三个解决方案，推荐程度依次降低：

1. 建议您添加按钮来触发拉流；

2. 或建议您在实例化SDK时开启静音订阅（参考是否静音订阅流），并在拉流成功后调用RTC静音/取消静音来取消静音。或者在UI上设置音量开关按钮，提醒用户打开声音；

3. 如您不采用以上两种方案，则需要提示用户点击页面任意位置解除声音播放限制（aliyun-avatar-sdk的兜底策略）；

拉流没有画面

1. 请检查当前页面协议是否为HTTPS，若不是，请更换成HTTPS；

2. 请检查构造函数是否被成功构建：当您输入的参数不合法时，使用new操作符实例化sdk会抛出错误；

3. 请检查服务端是否成功调用StartInstance接口，以及前端是否将服务端的返回正确地填写到构造函数的入参里（注意StartInstance返回的字段名为大驼峰，需要手动转为小驼峰输入到入参里）；

4. 将options.rtc.chromaKey手动置为false，先关闭透明背景功能，尝试是否有画面；

5. 请检查自定义的onInitSuccess事件是否被触发：若已经触发，请继续下面的步骤排查，若没有被触发，请提交工单与我们联系；

6. 排查完以上问题后，请按照下图所示步骤继续排查客户端是否收到流

说明如下：

7. 若该图表为空，可能是浏览器插件导致，为过滤浏览器插件影响，请执行以下操作之一：

   1. 关闭所有浏览器插件，重新打开页面

   2. 或打开chrome浏览器无痕窗口，重新打开页面

   3. 或更换其他浏览器，重新打开页面

   目前已知会影响RTC正常拉流的浏览器插件：PureVPN Proxy；

8. 如关闭所有浏览器插件并更换其他浏览器仍没有画面，请提交工单与我们联系；

本地调试正常，线上环境报错

出现这种错误的原因可能是您采用的打包工具与aliyun-avatar-sdk不兼容，您可以尝试使用CDN的方式引入aliyun-avatar-sdk。详情参考CDN引入。

PC端调试正常，移动端无画面

出现这种情况可能是因为移动端播放限制，请尝试给您的video标签添加如下属性：

<video
  webkit-playsinline="true"
  x5-playsinline="true"
  x-webkit-airplay="allow"
  playsInline="true"
  muted
/>

如何获取当前流媒体音量

// 以播报数字人为例，互动数字人同理
// 注意broadcastingAvatarSDK是实例化后的对象，不是BroadcastingAvatarSDK构造函数
/* global broadcastingAvatarSDK */
broadcastingAvatarSDK.rtc.aliRtcEngine.enableAudioVolumeIndicator = true;
broadcastingAvatarSDK.rtc.aliRtcEngine.on("onAudioLevel", async (data) => {
  const audio = data[0];
  console.log(audio.level); // 当前音量大小，为0说明当前无音频数据
});

附录

错误码表

AliRtc 音视频服务错误

触发onError回调时，source字段为"AliRtc"时，标志为阿里云RTC错误，详见

Web端错误码_音视频通信-阿里云帮助中心

数字人服务错误/警告

触发onError/onWarning回调时，source字段为"Avatar"时，标志为数字人服务/本地客户端异常，该异常分为两类：

• 错误：阻塞SDK功能正常使用，通过onError事件抛出；

• 警告：不阻塞SDK主链路使用，通过onWarning事件抛出；

详见下表：

各平台浏览器兼容性

兼容性测试

1. 访问https://avatar.console.aliyun.com/；

2. 左侧菜单进入【开发者中心】-【项目管理】，点击卡片上的【配置】进入配置页；

3. 在配置页点击【保存并测试】，耐心等待数字人加载；若数字人拉流成功，且与数字人对话成功（针对互动数字人），说明浏览器兼容性没有问题；