当前版本号 2.2.7
配套使用 TRTC SDK 定制化版本,需要在 App 的 build.gradle 配置中增加指定版本的 TRTC 依赖。
dependencies {implementation 'com.tencent.liteav.customize:LiteAVSDK_TRTC:13.0.0.19666'... 其他依赖}
1. Virtualman.init(VirtualmanParams,callback,WebSocketListener) 数智人初始化接口
VirtualmanParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
appkey | String | 必要参数 | 数智人 key,通过交互数智人平台创建的数智人的标识 appkey |
accessToken | String | 必要参数 | 数智人 accessToken,通过交互数智人平台创建的数智人的 accessToken |
httpOrigin | String | 可选参数 | 设置后 HTTP 请求都按这个 origin 设置,不设置时请求公有云地址 |
infoVisible | Boolean | 可选参数 | 是否展示 session 信息,默认为 true 则展示 session 信息,设置为 false 隐藏 |
virtualmanProjectParams | VirtualmanProjectParams | 可选参数 | 用于按 projectId 建流 注意: 如果 projectId 建流和 assetKey 建流都填写,以 projectId 建流优先。 |
assetVirtualmanParams | AssetVirtualmanParams | 可选参数 | 用于按 assetKey 建流 |
VirtualmanProjectParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
driverType | Int | 可选参数 | 驱动方式。默认值 3。 |
virtualmanProjectId | String | 必要参数 | 数智人项目 ID。 |
userId | String | 可选参数 | 用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用 ANDROID_ID 注意: 当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。 |
extraInfo | ExtraInfo | 可选参数 | 建流扩展参数。 |
protocolOption | ProtocolOption | 可选参数 | 用于配置外部 TRTC 应用。 |
AssetVirtualmanParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
driverType | Int | 可选参数 | 驱动方式。默认值 3。 |
assetVirtualmanKey | String | 必要参数 | 资产数智人 key(assetKey)。 |
userId | String | 可选参数 | 用户的唯一标识,由调用方自己维护,以相同的 UserId 创建新流,会导致上一个该 UserId 流关闭。默认使用 ANDROID_ID。 注意: 当使用 TRTC 协议时,该参数为数智人进房用户,调用方自身进房用户不能与该用户相同,如果相同会将数智人踢出房间,导致断流。 |
extraInfo | ExtraInfo | 可选参数 | 建流扩展参数。 |
protocolOption | ProtocolOption | 可选参数 | 用于配置外部 TRTC 应用。 |
ExtraInfo 参数说明(可选)
参数名称 | 数据类型 | 参数类型 | 说明 |
alphaChannelEnable | Boolean | 可选参数 | 是否开启透明通道。默认值 false。 |
ProtocolOption 参数说明(可选,用于配置外部 TRTC 应用)
参数名称 | 数据类型 | 参数类型 | 说明 |
trtcUseExternalApp | Boolean | 可选参数 | 是否使用外部 TRTC AppId,如果不使用,将使用数智人平台统一的 TRTC AppId。 注意: 数智人平台统一的 TRTC AppId,仅用于调试阶段,投产时,由用户自行在腾讯云申请 TRTC AppId。 |
trtcAppId | String | 条件必填 | |
trtcRoomId | Int | 条件必填 | TRTC 数字房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。数字房间号最大值为4294967294。 注意: 要和trtcAutoGenRoomIdType的房间号类型匹配。 |
trtcStrRoomId | String | 条件必填 | TRTC 数字房间号。使用外部 TRTC AppId 时,trtcRoomId 和 trtcStrRoomId 必填其一。 注意: 要和trtcAutoGenRoomIdType的房间号类型匹配。 |
trtcAutoGenRoomIdType | Int | 可选参数 | 房间号类型。0:数字类型,1:字符串类型,默认数字类型。 |
trtcUserSig | String | 条件必填 | TRTC 数智人用户签名(使用外部 TRTC AppId 时必填,计算签名时使用的用户名要与上面的userld参数的值保持一致,数智人需要使用该签名才能加入房间),计算方式请参见 实时音视频-用户鉴权。 |
trtcPrivateMapKey | String | 可选参数 | TRTC 数智人用户权限票据。 |
clientUserId | String | 条件必填 | 客户侧用户 ID。使用外部 TRTC AppId 时必填。 注意: 调用方自身进房用户,不能与数智人的 userId 相同,如果相同会将数智人踢出房间,导致断流。 |
clientUserSig | String | 条件必填 | |
clientPrivateMapKey | String | 可选参数 | 客户侧用户权限票据。 |
代码示例
// 资产建流mVirtualmanParams.appkey = Config.APP_KEYmVirtualmanParams.accesstoken = Config.ACCESS_TOKENmVirtualmanParams.assetVirtualmanParams = AssetVirtualmanParams()mVirtualmanParams.assetVirtualmanParams?.assetVirtualmanKey = Config.ASSET_VIRTUALMAN_KEYmVirtualmanParams.assetVirtualmanParams?.extraInfo = ExtraInfo()mVirtualmanParams.assetVirtualmanParams?.extraInfo?.alphaChannelEnable = falsemVirtualman.init(mVirtualmanParams, { result ->Log.i(TAG, "---------------------------------------------------")Log.i(TAG, result.toString())}, StreamWebSocketListener())// 项目建流mVirtualmanParams.appkey = Config.APP_KEYmVirtualmanParams.accesstoken = Config.ACCESS_TOKENmVirtualmanParams.virtualmanProjectParams = VirtualmanProjectParams()mVirtualmanParams.virtualmanProjectParams?.virtualmanProjectId = Config.VIRTUALMAN_PROJECT_IDmVirtualmanParams.virtualmanProjectParams?.extraInfo = ExtraInfo()mVirtualmanParams.virtualmanProjectParams?.extraInfo?.alphaChannelEnable = truemVirtualman.init(mVirtualmanParams, { result ->Log.i(TAG, "---------------------------------------------------")Log.i(TAG, result.toString())}, StreamWebSocketListener())
callback 参数说明
初始化回调函数
WebSocketListener 参数说明(可选)
方法 | 说明 |
onClosed | 关闭握手完成,连接正常关闭时调用。 |
onClosing | 收到对方的关闭帧,但握手尚未完成时调用。 |
onFailure | 连接异常断开(网络错误、超时等)时调用。 |
onMessage | 在收到文本类型消息时调用。 |
onOpen | websocket连接成功时调用。 |
2. Virtualman.sendText(params: SendTextParams) 发送文本接口
SendTextParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
text | String | 必要参数 | 对数智人要发送的文本。 |
isNewChat | Boolean | 可选参数 | 是否开启新对话。默认值 false。 |
reqId | String | 可选参数 | 单次驱动的唯一标识, 32位的 UUID(不包含‘-’)。 注意: 每次发送都新生成一个 ReqId。 |
videoSeiInfo | String | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。 当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明。 |
3. Virtualman.sendStreamText(SendStreamTextParams) 流式发送文本接口
SendStreamTextParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
reqId | String | 必要参数 | 单次驱动的唯一标识。每一段流式文本指定一个32位 UUID 值(不包含‘-’)。 注意: 每一段流式文本序列指定一个 ReqId,而不是每一次请求指定一个。 值得注意的是,在发送 final 包时仍然使用的是指定的这一个 ReqId,不需要再生成一个。 |
text | String | 必要参数 | 流式文本内容,只需要发送增量的文本。每个片包字符串长度限制 2000 字节。 注意: 子句模式发送要求: 1. 输入文本应为完整的句子序列,例如以,。!?等标点符号分割的文本。 2. 单个子句长度应大于10个汉字或单词。 非子句模式发送要求: 1. 流式非子句不支持 Text 中带 SSML 标签。 2. 发送速度不能过慢,过慢会导致出现非预期的 SpeakStatus,推荐发送速度与大模型返回数据的速度一致。 |
seq | Int | 必要参数 | 流式文本片包序号,序号必须从 1 开始。 |
isFinal | Boolean | 可选参数 | 用于标记本次流式文本驱动是否结束,默认值 false。 注意: 1. 发送 final 包的时机: 当流式文本驱动指令的文本内容 Text 都已发送完毕后,需要再发送一个 IsFinal=true 的驱动指令(这里简称 final 包,Text 字段可带有文本内容也可以是空串),来结束当次流式文本驱动,使数字人回到静默状态。 2. 没有及时发送 final 包会出现的问题: 对于流式文本驱动指令,包含子句模式与非子句模式,都可能会出现数智人播报期间卡顿的问题。 |
isSentence | Boolean | 可选参数 | 是否是子句模式,缺省值:false。为 true 服务端不会做重新组句。 |
isInsertSentence | Boolean | 可选参数 | 是否是插入的子句,缺省值:false。为 true 并且是子句模式则表示当前分片需要插播。 |
videoSeiInfo | String | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。 当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明。 |
4. Virtualman.textDrive(params: TextDriveParams) 纯文本驱动接口
在使用对话服务时,调用此接口用于使用不带对话服务的纯文本驱动,text 为文本驱动的内容。
TextDriveParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
text | String | 必要参数 | 纯文本驱动的内容。 |
reqId | String | 可选参数 | 单次驱动的唯一标识, 32位的 UUID(不包含‘-’)。 注意: 每次发送都新生成一个 ReqId。 |
videoSeiInfo | String | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。 当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明。 |
5. Virtualman.sendAudio(SendAudioParams) 发送音频驱动接口
SendAudioParams 参数说明
参数名称 | 数据类型 | 参数类型 | 说明 |
reqId | String | 必要参数 | 单次驱动的唯一标识。每一段音频指定一个32位 UUID 值(不包含‘-’)。 注意: 每一段流式音频序列指定一个 ReqId,而不是单独一次音频分片请求指定一个。 值得注意的是,在发送 final 包时仍然使用的是指定的这一个 ReqId,不需要再生成一个。 |
audio | String | 必要参数 | 音频原始数据的 byte 数组,经 Base64 编码后的字符串。只支持: 格式:PCM 采样率:16kHz 采样位深:16bits 声道:单声道 |
seq | Int | 必要参数 | 流式文本片包序号,序号必须从 1 开始。 |
isFinal | Boolean | 可选参数 | 用于标记本次音频驱动是否结束,默认值 false。 注意: 当数据包发送完毕后,必须再发送一个 IsFinal=true 的空数据包(Audio 字段填空串)结束当次音频驱动使数字人回到静默状态。 没有及时发送 final 包会出现的问题: 1. 可能会出现数智人播报期间卡顿的问题。 2. 后台在指定时间间隔(默认2秒)内既没收到音频包又没收到 IsFinal=true 的尾包,则后台会自动补一个 IsFinal=true 的尾包,使数智人进入静默状态。 |
videoSeiInfo | String | 可选参数 | 需要在视频流 SEI 中携带的信息,字符串内容为 JSON 格式。发送后会在视频流播报本次响应时在 SEI 中携带。 当前仅支持 2D 形象,视频流中信息说明请参见 视频流嵌入信息说明。 |
6. Virtualman.stop() 打断文本播报
在流式或非流式驱动播报时,调用此接口用于打断当前文本播报。
注意:
需要等到 WebSocket 下行消息返回 TextStart 标记后才可发送打断请求。
7. Virtualman.setSmartActionEnabled(value: Boolean) 开启智能动作
设置是否开启智能动作,缺省值:false。为 true 并且输入的文本或者话术增强后的文本没有动作标签则会生成智能动作。
8. Virtualman.statSession(callback) 查询当前会话的状态
9. Virtualman.listSessionOfUin(callback) 查询某个 uin 账号所有进行中的会话
10. Virtualman.listSessionOfProjectid(callback) 查询数智人项目下的会话列表
11. Virtualman.close() 数智人销毁接口
在 activity onDestroy 中或需要的时机调用关闭的方法以关闭数智人流,否则会占用后台资源。
12. Virtualman.isWebSocketConnected() 检查 WebSocket 连接状态
用于检查当前 WebSocket 是否处于连接状态。
返回值:Boolean,true 表示已连接,false 表示未连接或已断开。
13. Virtualman.reconnectWebSocket() 重新建立 WebSocket 连接
用于在 WebSocket 断开后重新建立连接。通常在网络恢复后调用。
14. Virtualman.setTRTCListener(listener: TRTCListener?) TRTC 事件监听回调
用于设置 TRTC 事件监听器。
TRTCListener 接口说明
方法 | 说明 |
onRecvSEIMsg(userId: String?, data: ByteArray?) | |
onFirstVideoFrame(userId: String?, streamType: Int, width: Int, height: Int) | |
onError(errCode: Int, errMsg: String?, extraInfo: Bundle?) | |
onConnectionLost() | TRTC与云端的连接已经断开。 |
onTryToReconnect() | TRTC正在尝试重新连接到云端。 |
onConnectionRecovery() | TRTC与云端的连接已经恢复。 |
onNetworkQuality(localQuality: TRTCQuality, remoteQuality: ArrayList?) | |
onStatistics(statistics: TRTCStatistics?) |
代码示例
mVirtualman.setTRTCListener(object : TRTCListener {override fun onRecvSEIMsg(userId: String?, data: ByteArray?) {if (data != null && data.isNotEmpty()) {Log.i(TAG, "收到SEI消息 - 用户ID: $userId, 消息大小: ${data.size}")// 如果数据长度>=17,解析JSON部分if (data.size >= 17) {try {val jsonBytes = data.sliceArray(16 until data.size)val jsonString = String(jsonBytes, Charsets.UTF_8)Log.i(TAG, "SEI JSON部分: $jsonString")} catch (e: Exception) {Log.e(TAG, "解析SEI JSON部分失败", e)}}}}})
获取TRTC实例的方案
警告:
1. 由于SDK内部也用到TRTC实例,所以调用close之前,在使用过程不要轻易销毁TRTC实例。
2. 通过TRTC的addListener添加的监听,要注意适当时机调用removeListener方法。防止监听事件重复添加。
// 可以直接获取到trtc实例trtcCloud = TRTCCloud.sharedInstance(applicationContext)// 通过 addListener 添加 SEI 监听(演示外部直接使用 TRTC 实例)trtcCloud?.addListener(object : TRTCCloudListener() {override fun onRecvSEIMsg(userId: String?, data: ByteArray?) {if (data != null && data.size > 16) {val jsonData = String(data, 16, data.size - 16, Charsets.UTF_8)Log.i(TAG, "[addListener] 收到SEI消息: userId=$userId, data=$jsonData")}}})
SDK内部重连逻辑的介绍
1. init新建流时,如果建流成功在轮询流状态过程遇到网络异常,有10s的重试机制保证流能建立成功。如果超时失败,回调里会有对应的错误信息。
2. websocket的事件相关
会收到onFailure代表websocket断开了,不要调用send相关方法,会失败。
会收到onOpen代表websocket重连成功,可以继续调用send相关方法。
SDK内部会监听TRTC的onNetworkQuality事件,当websocket断开时,网络质量是1-5时,websocket会尝试重连。如果重连时流已经失效,onMessage事件里会有相关错误信息。