星尘交互数字人iOS SDK标准化文档

概述

星尘videochat_ios_sdk是通义星尘推出的一个实时流媒体数字人iOS SDK(framework)，具备低延迟、高性能、高并发、跨平台等优势, 结合阿里云的RTC、语音交互、渲染引擎、脸部和肢体驱动等技术，提供多种数字人解决方案，帮助企业和开发者快速集成数字人，打造数字人各种场景应用。

产品优势

• 高性能低延迟

• 轻松集成、标准化输出

• 多种数字人解决方案提供支持

产品能力

• 云端渲染数字人

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

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

接入前须知

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

• 云端渲染数字人、端测渲染(端到端)数字人的语音交互模式主要有三种模式：push2talk模式、tap2talk模式、duplex双工模式

• 在push2talk模式下，用户需要像类似钉钉发送语音消息那样，通过发送一段音频，来触发语音交互

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

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

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

• 星尘官网上的ApiKey并没有包含前缀Bearer 头，在初始化SDK的时候，请开发者自行添加前缀头，'Bearer ' + ApiKey, 具体可见如下示例项目中的代码或快速集成说明。

接入方法

Xcode framework集成

环境配置

Xcode 14及以上

加载SDK和依赖

在Xcode新建项目，将以下frameworks导入项目工程中 videochat_ios_sdk.framework AliVCSDK_ARTC.framework

alivcffmpeg.framework

权限相关

• SDK和数字人交互需要用到录音权限，在Info.plist文件中增加如下代码：

    <key>NSMicrophoneUsageDescription</key>

    <string>{使用麦克风的原因描述}</string>

云端渲染数字人

示例项目

本示例项目提供了信息录入的界面，包含数字人生成和退出的入口，并且支持push2talk、tap2talk、duplex三种语音交互模式下切换。

下载

从OSS上下载videochat_ios_demo_2biz 项目压缩包，并进行解压。

文件结构

解压后的示例项目文件架构如下：

videochat_ios_demo
├─videochat_ios_demo.xcodeproj
├─videochat_ios_sdk.framework
├─AliVCSDK_ARTC.framework
├─alivcffmpeg.framework
├─SnapKit.framework
├─videochat_ios_demo
|  ├─ConfigViewController.swift
|  ├─VideoChatViewController.swift
|	 ├─SceneDelegate.swift
|  └ ...

安装依赖并运行示例项目

在解压后的文件夹中双击打开videochat_ios_demo.xcodeproj，默认在Xcode中加载。

Xode登录Apple账号，在选择对应的Team，并且勾选Automatically Manage Signing.

设置完成后，点击左上角►运行项目。

在页面上录入对应的信息，然后点击 生成数字人 ，即可看到数字人交互页面。

请注意：云端渲染数字人的数字人资产ID和数字人模型ID请保持一致，均为数字人资产ID

首次启动示例项目并生成数字人后，语音交互模式默认以duplex双工模式的启动。

如果想要切换模式，点击页面顶部进行切换模式。每次切换模式后，都要重新生成数字人。

快速集成

新建云端渲染数字人实例

云端渲染数字人支持三种语音交互模式，分别是duplex双工、tap2talk、push2talk。这三种语音交互模式的取值可以通过SDK中的TYVoiceChatMode枚举值获取。

请注意：云端渲染数字人的数字人资产ID和数字人模型ID请保持一致，均为数字人资产ID

self.avatar = 
TYVideoChat(enableVolumeDetection: true,
            params: TYRTCAuthParams(type: .Avatar, // 云渲染交互模式
                                    modelId: 'xingchen-plus-v2'， //大模型Id，可默认 
                                    voiceId: "",  // 输入从星尘官网上获取的语音ID
                                    avatarId: "", // 输入从星尘官网上获取的数字人资产I
                                    mode: .duplex, // 设置语音交互模式, 可选duplex，tap2talk, push2talk
                                    appId: "",  // 预留字段，先临时写死123
                                    characterId: "", // 输入从星尘官网上获取的角色ID
                                    userId: "", //用户Id，建议使用唯一值
                                    extras: [
                                        // 开发者一般不需要设置此配置，设置后会影响到SDK内部的LLM语音模型
                                        'parameters': [
                                            // LLM语言模型的回复多样性
                                            'topP': 0.1,
                                            // LLM语言模型的回复发散度
                                            'temperature': 1.0,
                                        ]
                                    ]),
            config: TYRequestConfig(headers: [
                  'Authorization': 'Bearer ' + ApiKey
              ], url: "https://nlp.aliyuncs.com/v2/api/videochat/initialize"))

设置RTC视频流容器

在数字人的ViewController里面创建视频流容器，然后在viewDidLoad方法内设置绑定RTC视频流。

let videoView = UIView()
override func viewDidLoad() {
    super.viewDidLoad()    
    view.addSubview(videoView)
    videoView.frame = view.bounds
    // 设置绑定RTC视频流View
    self.avatar.setupRTCView(videoView)
}

绑定回调

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

• onFirstFrameReceived

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

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

• onReadyToSpeech

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

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

• onErrorReceived

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

avatar.onErrorReceived = { err in
  print('数字人内部发生错误:' + err.code + ' ' + err.message)
}

• onStateChanged

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

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

// 数字人状态
avatar.onStateChanged = { tyState in
  print('当前数字人状态' + tyState)
}

• onVolumeChanged

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

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

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

• onMessageReceived

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

avatar.onMessageReceived = { msg in
     if(msg.type == TYVoiceChatMessageType.speaking) {
         print("用户的对话文本内容", msg.text)
     } else {
         print("数字人的反馈文本内容", msg.text)
     }
}

初始化

云端渲染数字人底层通过阿里云RTC进行音视频流的传输，所以需要挂载在一个video元素上。

avatar.start()

暂停收音/恢复收音

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

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

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

发送语音和结束语音

发送语音和结束语音主要用于push2talk模式下，用户调用API，告知SDK开始发送语音和结束语音。

// 发送语音
avatar.sendSpeech()
// 结束语音
avatar.stopSpeech()

打断

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

avatar.interrupt()

指定应答内容

在默认情况下，用户输入的语音如果出现违规的情况下, 数字人是不会做出反馈的。指定应答内容可以让数字人使用传入的文本作为回复。

请注意：如果强制反馈的文本也出现违规的情况，那么数字人同样不会做出反馈。TYRequestToRespondType.prompt表示把文本送到SDK内部的LLM服务进行回答TYRequestToRespondType.transcript表示把文本直接转成语音

avatar.requestToRespond(type: TYRequestToRespondType, text: String)

退出

在离开数字人页面或更换数字人角色的时候，都要调用此方法。否则页面中会存在多个数字人实例，导致互相影响。

avatar.exit()

附录

接口说明

SDK提供了标准的TypeScript Api类型声明文件，详情可以在安装依赖包中的xingchenAvatar.d.ts文件中进行查看。

网页版API文档，请参考Xingchen-Avatar-Sdk API

错误码

网关服务错误

云端渲染、端测渲染(端到端)数字人错误码

RTC错误

WebSocket错误

语音服务错误

兼容性

• 支持系统iOS14及以上手机，建议内存至少4GB保证性能，暂不支持模拟器上测试。

• 云端渲染数字人底层均依赖阿里云RTC的能力。具体兼容性请参考：iOS SDK