数字人流媒体服务WebSDK

接入前须知

1. aliyun-avatar-sdk不包含操作服务端实例的接口（如启动数字人、结束数字人、播报文本等功能），如有需要请参考OpenAPI文档；

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

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

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

5. 由于chrome对自动播放的限制，禁止自动播放音频，如果您的页面在没有任何用户点击的情况下自动拉流（例如用js触发的方式自动拉流），会出现数字人无声音的问题，这种情况有三个解决方案，推荐程度依次降低：

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

   2. 或建议您在实例化SDK时开启静音订阅（参考是否静音订阅流），并在UI上设置音量开关按钮，提醒用户打开声音；

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

接入方法

在线安装

可以通过npm安装

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

离线安装

从OSS下载SDK包

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

SDK使用文档

互动数字人 - DialogAvatarSDK

快速入门

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

/*
 * 获取建立im和拉rtc流的关键信息
 */
// StartInstanceRes：从服务端StartInstance接口返回值
const { requestId, 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: '', // 建立IM连接的websocket地址
    maxReconnectTimeout: 300000, // 断线重连最大尝试时间(ms)，超出这个时间仍未重连成功将抛出断线重连超时错误
    audio: {
      autoStartRecord: false, // 是否在初始化过程中自动开启浏览器录音
      interval: 100, // 音频采集间隔(ms)，注意不能小于60ms，不能大于1000ms，否则会抛出错误，音频单通道16K 16bit
      autoDodge: false, // 是否开启音频闪避
    },
    rtc: {
      muted: false, // 是否静音订阅流
    },
  },
  // 初始化成功回调
  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);
  },
  // 收音开始回调
  onRecordingStart: () => {
    // 可以在ui上提示用户
  },
  // 收音结束回调
  onRecordingStop: () => {
    // 可以在ui上提示用户
  },
  // ASR下发文本回调
  onASR: (text, sentenceId) => {
    console.log(`Answer: ${text}`);
    console.log(`sentenceId: ${sentenceId}`);
  },
  // 数字人回答下发文本回调
  onAnswer: (text, sentenceId) => {
    console.log(`Answer: ${text}`);
    console.log(`sentenceId: ${sentenceId}`);
  },
  // 未知im消息回调，用于接收后端业务增加新的消息类型
  onUnknownIMMessage: (msg) => {
    console.log(msg);
  },
});

/*
 * 初始化
 */
dialogAvatarSDK
  .init()
  .then(() => {
    // 等同于onInitSuccess
    console.log('IM连接成功，RTC拉流成功');
  })
  .catch((e) => {
    // 同样的错误也会被onError捕获
    console.log(e);
  });

dialogAvatarSDK.openAutoDodge(); // 开启音频闪避
dialogAvatarSDK.stopRecording(); // 手动停止收音/自定义音频采集，会触发onRecordingStop
dialogAvatarSDK.startRecording().then(()=>{
	// 手动开启收音/自定义音频采集，会触发onRecordingStart
	console.log('录音成功');
});
dialogAvatarSDK.destroy(); // 销毁实例

新建实例

构造函数入参如下表：

绑定回调

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

• onInitSuccess 初始化成功回调

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

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

• onIMInitSuccess IM初始化成功回调

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

• onRtcInitSuccess RTC初始化成功回调

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

• onError 错误回调

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

回调入参e数据结构：

• onASR ASR下发文本回调

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

回调入参说明：

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

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

回调入参说明：

• onRecordingStart 收音开始回调

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

• onRecordingStop 收音结束回调

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

初始化

初始核心流程：

1. 建立im连接;

2. rtc拉流；

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

• init 初始化回调

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

暂停/开始收音

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

RTC静音/取消静音

dialogAvatarSDK.muteRtc();
dialogAvatarSDK.unMuteRtc();

高级功能

• 暴露阿里云RTC原始对象

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

• 暴露Websocket原始对象

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

• 音频闪避

自动检测RTC视频流数字人说话暂停收音，有两种开启方式：

1. 自动开启：

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

2. 手动开启：

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

销毁实例

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

dialogAvatarSDK.destroy();

播报数字人 - BroadcastingAvatarSDK

快速入门

/*
 * 获取建立im和拉rtc流的关键信息
 */
// StartInstanceRes：从服务端StartInstance接口返回值
const { requestId, 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, // 是否静音订阅流
    },
  },
  // 初始化成功回调
  onInitSuccess: () => {
    console.log('RTC拉流成功');
  },
  // 错误回调
  onError: (e) => {
    console.error(e);
  },
});

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

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

新建实例

构造函数入参

绑定回调

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

• onInitSuccess 初始化成功回调

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

• onError 错误回调

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

回调入参e数据结构：

初始化

初始化核心流程：rtc拉流

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

RTC静音/取消静音

broadcastingAvatarSDK.muteRtc();
broadcastingAvatarSDK.unMuteRtc();

高级功能

• 暴露阿里云RTC原始对象

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

销毁实例

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

broadcastingAvatarSDK.destroy();

附录

错误码表

AliRtc 音视频服务错误

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

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

数字人服务错误

触发onError回调时，source字段为"Avatar"时，标志为数字人服务/本地客户端错误，详见下表

各平台浏览器兼容性

兼容性测试

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

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

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