概述

星塵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