概述

星塵Xingchen-Avatar-SDK是通義星塵推出的一個實時流媒體數字人Web SDK(JavaScript 庫)，具備低延遲、高性能、高并發、跨平臺等優勢, 結合阿里云的RTC、語音交互、渲染引擎、臉部和肢體驅動等技術，提供多種數字人解決方案，幫助企業和開發者快速集成數字人，打造數字人各種場景應用。

產品優勢

• 高性能低延遲

• 輕松集成、標準化輸出

• 多種數字人解決方案提供支持

產品能力

• 云端渲染數字人

• 云端渲染數字人是通過阿里云RTC提供視頻流訂閱，SDK在瀏覽器上拉取視頻流呈現數字人的解決方案。

• 云端渲染數字人具備完整的語音交互、臉部和肢體驅動能力，提供數字人打斷、多種對話模式。

• 端測渲染(端到端)數字人

• 端測渲染數字人是通過阿里云RTC提供音頻和模型臉部肢體動作數據，SDK在瀏覽器上通過拉取數據并使用WebGL渲染數字人的解決方案。

• 端測渲染(端到端)數據人同樣具備完整的語音交互、臉部和肢體驅動能力，同樣提供數字人打斷、多種對話模式。

• 單獨輸出數字人

• 單獨輸出數字人是基于標準WebSocket能力，接入方提供第三方LLM返回的二進制音頻數據，SDK根據第三方提供的音頻數據在瀏覽器上使用WebGL渲染數字人的解決方案。

• 單獨輸出數字人由于依托于接入方提供的二進制音頻數據，所以不具備完整的語音交互。但是會根據第三方的二進制音頻數據做出同樣的臉部和肢體驅動。

接入前須知

• 受瀏覽器底層WebSocket、底層錄音權限、WebRTC等限制，本地開發環境僅支持使用localhost運行。生產環境上頁面協議請使用HTTPS,否則會出現錄音權限獲取失敗、拉流播放失敗等問題。

• 云端渲染數字人、端測渲染(端到端)數字人的語音交互模式主要有三種模式：push2talk模式、tap2talk模式、duplex雙工模式

• 在push2talk模式下，用戶需要像類似釘釘發送語音消息那樣，通過發送一段音頻，來觸發語音交互

• 在tap2talk模式下，SDK內部的語音服務會實時識別用戶的語音輸入。但是用戶想打斷數字人，需要通過額外事件來觸發，比如點擊屏幕，或者點擊某按鈕。

• 在duplex雙工模式下，SDK內部的語音服務會實時識別用戶的語音輸入。數字人在說話狀態下，仍可以接受用戶的語音打斷信號。

  • 在duplex雙工模式，容易受到外部環境音的影響導致觸發頻繁打斷，請在相對安靜的環境下使用雙工模式。

• 星塵官網上的ApiKey并沒有包含前綴Bearer 頭，在初始化SDK的時候，請開發者自行添加前綴頭，'Bearer ' + ApiKey, 具體可見如下示例項目中的代碼或快速集成說明。

接入方法

Npm集成

請根據自己使用的包管理器，選擇對應的命令，安裝xingchen-avatar-sdk依賴包

當前版本是1.0.0-alpha.8

// npm包管理器
npm i xingchen-avatar-sdk@1.0.0-alpha.8
// pnpm包管理器
pnpm i xingchen-avatar-sdk@1.0.0-alpha.8
// yarn包管理器
yarn add xingchen-avatar-sdk@1.0.0-alpha.8

云端渲染數字人

示例項目

本示例項目使用Vue框架。并且提供了信息錄入的界面，包含數字人生成和退出的入口，并且支持push2talk、tap2talk、duplex三種語音交互模式下切換。

下載

從OSS上下載示例項目cloud-avatar.zip壓縮包，并進行解壓

文件結構

解壓后的示例項目文件架構如下：

cloud-avatar
├─index.html
├─package.json
├─vite.config.js
├─src
|  ├─App.vue
|  ├─main.js
|  └style.css

安裝依賴并運行示例項目

在解壓后的文件夾中執行如下命令：

// 安裝依賴
npm install
// 啟動
npm run dev

運行后，在瀏覽器上打開localhost:5173即可看到示例項目的啟動界面

在頁面上錄入對應的信息，然后點擊生成數字人，即可在瀏覽器右側看到數字人。

首次啟動示例項目并生成數字人后，語音交互模式默認以duplex雙工模式的啟動。

如果想要切換模式，點擊頁面左側底部的切換按鈕進行切換。每次切換模式后，都要重新生成數字人。

快速集成

設置掛載元素

云端渲染數字人底層通過阿里云RTC進行音視頻流的傳輸，需要掛載在一個video元素上。所以開發者要在頁面html中先添加video容器元素。

<video class='container' muted></video>

新建云端渲染數字人實例

云端渲染數字人支持三種語音交互模式，分別是duplex雙工、tap2talk、push2talk。這三種語音交互模式的取值可以通過SDK中的TYVoiceChatMode枚舉值獲取。

import { createCloudAvatar, type CloudAvatar, TYVoiceChatMode, TYAvatarType, TYVoiceChatState, TYError, type TYVoiceChatMessage, TYVoiceChatMessageType, TYVolumeSourceType, nanoid } from 'xingchen-avatar-sdk'
// 創建云端渲染數字人實例
const avatar = createCloudAvatar({
  type: TYAvatarType.CloudAvatar,
  // 設置語音交互模式
  mode: TYVoiceChatMode.duplex,
  // 輸入從星塵官網上獲取的數字人ID
  avatarId: '',
  // 輸入從星塵官網上獲取的AvatarModelId
  avatarModelId: '',
  // 輸入從星塵官網上獲取的語音ID
  voiceId: '',
  // 輸入從星塵官網上獲取的應用ID
  characterId: '',
  // 預留字段，先臨時寫死123
  appId: '123',
  // 預留字段，每次初始化生成一個隨機值
  userId: nanoid(),
  extras: {
    // 開發者一般不需要設置此配置，設置后會影響到SDK內部的LLM語音模型
    parameters: {
      // LLM語言模型的回復多樣性
      topP: 0.1,
      // LLM語言模型的回復發散度
      temperature: 1.0,
    }
  }
}, {
  headers: {
    // 輸入從星塵官網上獲取的ApiKey
    Authorization: 'Bearer ' + '在此處填入ApiKey'
  }
})

請注意：默認情況下，若 SDK 完成交互后未進行持續對話，系統將在一分鐘后自動斷開鏈接，以確保資源的高效利用和安全性。若您因業務需求，需對鏈接的心跳模式進行自定義修改，可在創建實例的第一個參數中額外配置 “keepAlive” 參數，從而靈活調整鏈接的維持狀態。

interface {
  // true表示每隔30s持續發送心跳，永遠不間斷
  // 傳入數值number類型（單位是毫秒），那么表示在傳入的時間范圍內，持續心跳，超過指定的時間后，將停止心跳。
  keepAlive: boolean | number
}

const avatar = createCloudAvatar({
  // 其他參數保持上面的實例
  // ......
  keepAlive: true
}, {
  headers: {
    // 輸入從星塵官網上獲取的ApiKey
    Authorization: 'Bearer ' + '在此處填入ApiKey'
  }
})

綁定回調

并不是所有回調都需要綁定，建議開發者根據業務開發需求進行綁定即可。

• onFirstFrameReceived

在數字人首頁畫面出現的時候觸發此回調

avatar.onFirstFrameReceived(() => {
  console.log('數字人渲染完畢')
})

• onReadyToSpeech

在數字人可以開始進行語音交互的時候觸發此回調

avatar.onReadyToSpeech(() => {
  console.log('可以進行語音交互了')
})

• onErrorReceived

在數字人內部出現錯誤的時候觸發此回調, 更多錯誤碼詳情見此教程的錯誤碼列表

avatar.onErrorReceived((err:TYError) => {
  console.log('數字人內部發生錯誤:' + err.code + ' ' + err.message)
})

• onStateChanged

在數字人內部狀態發生變化的時候觸發此回調，詳情見SDK中的TYVoiceChatState類型聲明。

云端數字人擁有三種狀態：Listening(傾聽)、Thinking(思考中)、Responding(反饋中)

// 數字人狀態
avatar.onStateChanged((tyState: TYVoiceChatState) => {
  console.log('當前數字人狀態' + tyState)
})

• onVolumeChanged

在數字人或者用戶說話音量發生變化的時候觸發此回調。回調返回的數據中，source為TYVolumeSourceType.mic的數據表示用戶自己說話的音量，source為TYVolumeSourceType.player的數據表示數字人的音量。詳情見SDK中的TYVolume和TYVolumeSourceType類型聲明。

請注意：SDK已將數字人的音量做了歸一化處理，數值大小范圍為0～1

avatar.onVolumeChanged((data: TYVolume) => {
  if(data.source === TYVolumeSourceType.mic) {
    console.log('用戶音量:' + data.volume)
  } else {
    console.log('數字人音量:' + data.volume)
  }
})

• onMessageReceived

在識別出數字人對話文本或用戶對話文本的時候觸發此回調，詳情見SDK中的TYVoiceChatMessage和TYVoiceChatMessageType類型聲明。

 avatar.onMessageReceived((msg: TYVoiceChatMessage) => {
  if(msg.type === TYVoiceChatMessageType.speaking) {
    console.log("用戶的對話文本內容", msg.text)
  } else {
    console.log("數字人的反饋文本內容", msg.text)
  }
})

初始化

云端渲染數字人底層通過阿里云RTC進行音視頻流的傳輸，所以需要掛載在一個video元素上。

// 或者傳入video元素
avatar.setupRTCView('.container')
avatar.start()

暫停收音/恢復收音

云端渲染數字人默認會自動開啟收音。暫停收音和恢復收音功能均可以在三種語音交互模式下有效，但一般主要用于duplex雙工語音交互場景。

在開啟雙工語音交互模式下，數字人容易受到外界環境音影響，開發者可以通過暫停收音的方法，讓數字人免受外界環境音影響。

// true：暫停收音
// false（默認值）：恢復收音
avatar.muteLocalMic(mute: boolean)

發送語音和結束語音

發送語音和結束語音主要用于push2talk模式下，用戶調用API，告知SDK開始發送語音和結束語音。

// 發送語音
avatar.sendSpeech()
// 結束語音
avatar.stopSpeech()

打斷

打斷方法常用于push2talk和tap2talk語音交互模式下，而在雙工模式下，SDK內部的語音服務本身就能識別用戶新的語音輸入進行打斷。

請注意：用戶主動打斷必須是在Responding反饋狀態下進行打斷。如果在Listening、Thinking狀態下進行打斷，那么后端服務將不會響應處理。

avatar.interrupt()

指定應答內容

在默認情況下，用戶輸入的語音如果出現違規的情況下, 數字人是不會做出反饋的。指定應答內容可以讓數字人使用傳入的文本作為回復。

請注意：如果強制反饋的文本也出現違規的情況，那么數字人同樣不會做出反饋。IRequestToRespondType.prompt表示把文本送到SDK內部的LLM服務進行回答IRequestToRespondType.transcript表示把文本直接轉成語音

avatar.requestToRespond(type: IRequestToRespondType, text: string)

退出

在離開數字人頁面或更換數字人角色的時候，都要調用此方法。否則頁面中會存在多個數字人實例，導致互相影響。

avatar.exit()

端測渲染(端到端)數字人

端測渲染(端到端)數字人的Api和云端渲染數字人的Api基本保持一致，最大區別是端測渲染(端到端)是在瀏覽器上通過WebGL進行渲染數字人，而非通過RTC拉視頻流的方式顯示數字人。

示例項目

本示例項目使用Vue框架。并且提供了信息錄入的界面，包含數字人生成和退出的入口，并且支持push2talk、tap2talk、duplex三種語音交互模式下切換。

下載

從OSS上下載示例項目local-avatar.zip壓縮包，并進行解壓

文件結構

解壓后的示例項目文件架構如下：

local-avatar
├─index.html
├─package.json
├─vite.config.js
├─src
|  ├─App.vue
|  ├─main.js
|  └style.css

安裝依賴并運行示例項目

在解壓后的文件夾中執行如下命令：

// 安裝依賴
npm install
// 啟動
npm run dev

運行后，在瀏覽器上打開localhost:5173即可看到示例項目的啟動界面

在頁面上錄入對應的信息，然后點擊生成數字人，即可在瀏覽器右側看到數字人。

首次啟動示例項目并生成數字人后，語音交互模式默認以duplex雙工模式的啟動。

如果想要切換模式，點擊頁面左側底部的切換按鈕進行切換。每次切換模式后，都要重新生成數字人。

快速集成

設置掛載元素

端測渲染(端到端)數字人底層通過WebGL加載模型并繪制數字人，所以開發者要在頁面html中先添加div容器元素。

<div class='container'></div>

新建端測渲染(端到端)數字人實例

端到端數字人支持三種語音交互模式，分別是duplex雙工、tap2talk、push2talk。這三種語音交互模式的取值可以通過SDK中的TYVoiceChatMode枚舉值獲取。

請注意：端測渲染(端到端)數字人的數字人ID和數字人AvatarModelId 不一樣

import { createLocalAvatar, TYVoiceChatMode, TYAvatarType, type LocalAvatar, type TYError, type TYVolume, TYVolumeSourceType, TYVoiceChatMessage, TYVoiceChatMessageType, nanoid } from 'xingchen-avatar-sdk'
// 創建云端數字人實例
avatar = createLocalAvatar({
    type: TYAvatarType.LocalAvatar,
    mode: TYVoiceChatMode.duplex,
    // 輸入從星塵官網上獲取的數字人ID
    avatarId: '',
    // 輸入從星塵官網上獲取的AvatarModelId
    avatarModelId: '',
    // 輸入從星塵官網上獲取的語音ID
    voiceId: '',
    // 輸入從星塵官網上獲取的應用ID
    characterId: '',
    // 預留字段，先臨時寫死123
    appId: '123',
    // 預留字段，每次初始化生成一個隨機值
    userId: nanoid(),
    extras: {
      // 開發者一般不需要設置此配置，設置后會影響到SDK內部的LLM語音模型
      parameters: {
        // LLM語言模型的回復多樣性
        topP: 0.1,
        // LLM語言模型的回復發散度
        temperature: 1.0,
      }
    }
  }, {
    headers: {
      // 輸入從星塵官網上獲取的ApiKey
      Authorization: 'Bearer ' + '在此處填入ApiKey'
    }
  })

請注意：默認情況下，若 SDK 完成交互后未進行持續對話，系統將在一分鐘后自動斷開鏈接，以確保資源的高效利用和安全性。若您因業務需求，需對鏈接的心跳模式進行自定義修改，可在創建實例的第一個參數中額外配置 “keepAlive” 參數，從而靈活調整鏈接的維持狀態。

interface {
  // true表示每隔30s持續發送心跳，永遠不間斷
  // 傳入數值number類型（單位是毫秒），那么表示在傳入的時間范圍內，持續心跳，超過指定的時間后，將停止心跳。
  keepAlive: boolean | number
}

const avatar = createCloudAvatar({
  // 其他參數保持上面的實例
  // ......
  keepAlive: true
}, {
  headers: {
    // 輸入從星塵官網上獲取的ApiKey
    Authorization: 'Bearer ' + '在此處填入ApiKey'
  }
})

綁定回調

并不是所有回調都需要綁定，建議開發者根據業務開發需求進行綁定即可。

• onFirstFrameReceived

在數字人首頁畫面出現的時候觸發此回調

avatar.onFirstFrameReceived(() => {
  console.log('數字人渲染完畢')
})

• onReadyToSpeech

在數字人可以開始進行語音交互的時候觸發此回調

avatar.onReadyToSpeech(() => {
  console.log('可以進行語音交互了')
})

• onErrorReceived

在數字人內部出現錯誤的時候觸發此回調, 更多錯誤碼詳情見此教程的錯誤碼列表

avatar.onErrorReceived((err:TYError) => {
  console.log('數字人內部發生錯誤:' + err.code + ' ' + err.message)
})

• onStateChanged

在數字人內部狀態發生變化的時候觸發此回調，詳情見SDK中的TYVoiceChatState類型聲明。

端到端數字人比云端渲染數字人多了一個Idle靜默狀態，擁有4種狀態：Idle(靜默)、Listening(傾聽)、Thinking(思考中)、Responding(反饋中)

// 數字人狀態
avatar.onStateChanged((tyState: TYVoiceChatState) => {
  console.log('當前數字人狀態' + tyState)
})

• onVolumeChanged

在數字人或者用戶說話音量發生變化的時候觸發此回調。回調返回的數據中，source為TYVolumeSourceType.mic的數據表示用戶自己說話的音量，source為TYVolumeSourceType.player的數據表示數字人的音量。詳情見SDK中的TYVolume和TYVolumeSourceType類型聲明。

請注意：SDK已將數字人的音量做了歸一化處理，數值大小范圍為0～1

在端測渲染(端到端)數字人中，SDK內部始終將數字人反饋的音量設置為標準播放音量1，所以只能監聽到用戶音量的變化回調。

avatar.onVolumeChanged((data: TYVolume) => {
    console.log('用戶音量:' + data.volume)
})

• onMessageReceived

在識別出數字人對話文本或用戶對話文本的時候觸發此回調，詳情見SDK中的TYVoiceChatMessage和TYVoiceChatMessageType類型聲明。

 avatar.onMessageReceived((msg: TYVoiceChatMessage) => {
  if(msg.type === TYVoiceChatMessageType.speaking) {
    console.log("用戶的對話文本內容", msg.text)
  } else {
    console.log("數字人的反饋文本內容", msg.text)
  }
})

初始化

端測渲染(端到端)數字人底層通過WebGL加載模型并繪制數字人，需要掛載在一個div元素上。

// 或者傳入div容器元素
avatar.setupRTCView('.container')
avatar.start()

在端測渲染(端到端)數字人中，提供了三種渲染模式來渲染數字人，分別是高性能、標準性能、低性能。高性能一般用于電腦，標準渲染模式用于高端手機，低性能用于嵌入式設備。默認會啟動標準的渲染模式，如果想使用高性能或低性能的渲染模式,請在調用start初始化渲染的時候，傳入額外的配置。

import { IRenderMode } from 'xingchen-avatar-sdk'
// 或者傳入div容器元素
avatar.setupRTCView('.container')
avatar.start({
  ext: {
    // 是否開啟陰影效果，默認是true。開啟陰影效果同樣會影響性能
    enableShadow: false,
    // 渲染模式
    renderMode: IRenderMode.Low
  }
})

暫停收音/恢復收音

端到端數字人默認會自動開啟收音。暫停收音和恢復收音功能均可以在三種語音交互模式下有效，但一般主要用于duplex雙工語音交互場景。

在開啟雙工語音交互模式下，數字人容易受到外界環境音影響，開發者可以通過暫停收音的方法，讓數字人免受外界環境音影響。

// true：暫停收音
// false（默認值）：恢復收音
avatar.muteLocalMic(mute: boolean)

發送語音和結束語音

發送語音和結束語音主要用于push2talk模式下，用戶調用API，告知SDK開始發送語音和結束語音。

// 發送語音
avatar.sendSpeech()
// 結束語音
avatar.stopSpeech()

打斷

打斷方法常用于push2talk和tap2talk語音交互模式下，而在雙工模式下，SDK內部的語音服務本身就能識別用戶新的語音輸入進行打斷。

請注意：用戶主動打斷必須是在Responding反饋狀態下進行打斷。如果在Listening、Thinking狀態下進行打斷，那么后端服務將不會響應處理。在Idle靜默狀態下，進行打斷，端測渲染將會進入Listening狀態。

avatar.interrupt()

指定應答內容

在默認情況下，用戶輸入的語音如果出現違規的情況下, 數字人是不會做出反饋的。指定應答內容可以讓數字人使用傳入的文本作為回復。

請注意：如果強制反饋的文本也出現違規的情況，那么數字人同樣不會做出反饋。IRequestToRespondType.prompt表示把文本送到SDK內部的LLM服務進行回答IRequestToRespondType.transcript表示把文本直接轉成語音

avatar.requestToRespond(type: IRequestToRespondType, text: string)

退出

在離開數字人頁面或更換數字人角色的時候，都要調用此方法。否則頁面中會存在多個數字人實例，導致互相影響。

avatar.exit()

單獨輸出數字人

示例項目

本示例項目使用Vue框架。并且提供了信息錄入的界面，包含數字人生成和退出的入口，并且支持通過試聽音頻和錄音功能模擬開發者輸入第三方LLM下發的二進制音頻流。

下載

從OSS上下載示例項目pure-avatar.zip壓縮包，并進行解壓

文件結構

解壓后的示例項目文件架構如下：

pure-avatar
├─index.html
├─package.json
├─vite.config.js
├─src
|  ├─App.vue
|  ├─main.js
|  └style.css

安裝依賴并運行示例項目

在解壓后的文件夾中執行如下命令：

// 安裝依賴
npm install
// 啟動
npm run dev

運行后，在瀏覽器上打開localhost:5173即可看到示例項目的啟動界面

在頁面上錄入對應的信息，然后點擊生成數字人，即可在瀏覽器右側看到數字人。

首次啟動示例項目并生成數字人后，數字人會處于靜默狀態，需要點擊試聽音頻或錄音后，數字人才會做出反饋

快速集成

設置掛載元素

單獨輸出數字人底層通過標準WebSocket協議接收第三方LLM傳入的二進制音頻流，并在瀏覽器上通過WebGL加載模型并繪制數字人。所以開發者要在頁面html中先添加div容器元素。

<div class='container'></div>

新建單獨輸出數字人實例

云端渲染數字人支持三種語音交互模式，分別是duplex雙工、tap2talk、push2talk。這三種語音交互模式的取值可以通過SDK中的TYVoiceChatMode枚舉值獲取。

請注意：端測渲染(端到端)數字人的數字人ID和數字人AvatarModelId 不一樣

import { createPureAvatar, type PureAvatar, type TYVoiceChatState, type TYError } from 'xingchen-avatar-sdk'
// 創建單獨輸出數字人實例
const avatar = createPureAvatar({
  // 輸入從星塵官網上獲取的數字人ID
  avatarId: '',
  // 輸入從星塵官網上獲取的AvatarModelId
  modelId: '',
  // 輸入從星塵官網上獲取的ApiKey
  xFagToken: `Bearer ` + '在此處輸入ApiKey'
})

請注意：默認情況下，若 SDK 完成交互后未進行持續對話，系統將在一分鐘后自動斷開鏈接，以確保資源的高效利用和安全性。若您因業務需求，需對鏈接的心跳模式進行自定義修改，可在創建實例的第一個參數中額外配置 “keepAlive” 參數，從而靈活調整鏈接的維持狀態。

interface {
  // true表示每隔30s持續發送心跳，永遠不間斷
  // 傳入數值number類型（單位是毫秒），那么表示在傳入的時間范圍內，持續心跳，超過指定的時間后，將停止心跳。
  keepAlive: boolean | number
}

const avatar = createPureAvatar({
  // 其他參數請參考上面的實例
  // ......
  keepAlive: true
})

綁定回調

并不是所有回調都需要綁定，建議開發者根據業務開發需求進行綁定即可。

• onFirstFrameReceived

在數字人首頁畫面出現的時候觸發此回調

avatar.onFirstFrameReceived(() => {
  console.log('數字人渲染完畢')
})

• onErrorReceived

在數字人內部出現錯誤的時候觸發此回調, 更多錯誤碼詳情見此教程的錯誤碼列表

avatar.onErrorReceived((err:TYError) => {
  console.log('數字人內部發生錯誤:' + err.code + ' ' + err.message)
})

• onStateChanged

在數字人內部狀態發生變化的時候觸發此回調，詳情見SDK中的TYVoiceChatState類型聲明。

單獨輸出數字人和端測渲染(端到端)數字人一樣，擁有4種狀態：Idle(靜默)、Listening(傾聽)、Thinking(思考中)、Responding(反饋中)

// 數字人狀態
avatar.onStateChanged((tyState: TYVoiceChatState) => {
  console.log('當前數字人狀態' + tyState)
})

初始化

云端渲染數字人底層通過阿里云RTC進行音視頻流的傳輸，所以需要掛載在一個video元素上。

// 或者傳入div元素
avatar.setupRTCView('.container')
avatar.start()

在單獨輸出數字人中，同樣提供了三種渲染模式來渲染數字人，分別是高性能、標準性能、低性能。高性能一般用于電腦，標準渲染模式用于高端手機，低性能用于嵌入式設備。默認會啟動標準的渲染模式，如果想使用高性能或低性能的渲染模式,請在調用start初始化渲染的時候，傳入額外的配置。

import { IRenderMode } from 'xingchen-avatar-sdk'
// 或者傳入div容器元素
// 或者傳入div元素
avatar.setupRTCView('.container')
avatar.start({
  ext: {
    // 是否開啟陰影效果，默認是true。開啟陰影效果同樣會影響性能
    enableShadow: false,
    // 渲染模式
    renderMode: IRenderMode.Low
  }
})

發送語音

在單獨輸出數字人下，開發者通過sendSpeech接口，可以將第三方LLM下發的二進制音頻流給到SDK內部的語音服務，驅動頁面上數字人做出響應。

請注意：目前單獨輸出數字人只能接受16 kHZ采樣速率的二進制音頻流

interface ISpeech {
  // 二進制音頻流
  audioData: Int8Array | Uint8Array
  // 用于告知SDK，當前二進制音頻流是否為第三方LLM每輪對話反饋的最后一片音頻數據。true表示最后一片，false表示不是最后一片
  endOfTask: boolean
  // 任意隨機值，但是第三方LLM每輪對話反饋的音頻片段，都要使用同一個taskId
  taskId: string
}

// 發送語音
avatar.sendSpeech(options:ISpeech)

打斷

請注意：用戶主動打斷必須是在Responding反饋狀態下進行打斷。如果在Listening、Thinking狀態下進行打斷，那么后端服務將不會響應處理。在Idle靜默狀態下，進行打斷，端測渲染將會進入Listening狀態。

avatar.interrupt()

切換數字人狀態

用戶在使用第三方LLM語音交互服務的時候，需要將數字人切換到對應的狀態。例如：Listening(傾聽)、思考(Thinking). 詳情見SDK中的TYVoiceChatState類型聲明。

avatar.changeState(state: TYVoiceChatState)

退出

在離開數字人頁面或更換數字人角色的時候，都要調用此方法。否則頁面中會存在多個數字人實例，導致互相影響。

avatar.exit()

附錄

接口說明

SDK提供了標準的TypeScript Api類型聲明文件，詳情可以在安裝依賴包中的xingchenAvatar.d.ts文件中進行查看。

網頁版API文檔，請參考Xingchen-Avatar-Sdk API

錯誤碼

網關服務錯誤

云端渲染、端測渲染(端到端)數字人錯誤碼

詳細枚舉值見SDK中的枚舉值GatewayErrorCode

RTC錯誤

詳細枚舉值見SDK中的枚舉值RTCErrorCode

WebSocket錯誤

詳細枚舉值見SDK中的枚舉值WSErrorCode

系統錯誤

詳細枚舉值見SDK中的枚舉值SystemErrorCode

語音服務錯誤

詳細枚舉值見SDK中的枚舉值VoiceChatErrorCode

URL協議限制

兼容性

• 目前SDK均不支持在原生的小程序開發上使用，但是可以嘗試通過webview的方式打開自己的業務網頁。開發者使用自己的業務網頁時需要在域名根目錄上添加小程序的校驗文件，校驗文件配置方案請參考各小程序平臺的接入方式。

• 云端渲染數字人和端測渲染(端到端)數字人，底層均依賴阿里云RTC的能力。具體兼容性請參考：阿里云ARTC Web SDK

• 單獨輸出數字人底層依賴標準WebSocket協議。具體兼容性請參考：WebSocket 兼容性