Alibaba Cloud Model Studio：語音合成 Sambert HarmonyOS SDK

使用 Sambert HarmonyOS SDK 將文字合成為高品質、富有表現力的語音。

使用者指南： 關於模型介紹和選型建議，請參見 語音合成-Sambert。

線上體驗：暫不支援。

請將 {WorkspaceId} 替換為真實的 Workspace ID。現有網域仍可正常使用。

NativeNui

本 SDK 基於 NativeNui 架構，透過回調機制處理語音合成事件。

架構特點：

• 執行個體模式：透過 new NativeNui(Constants.ModeType.MODE_TTS) 建立語音合成執行個體。
• 回調驅動：透過 NuiTtsSdkListener 介面接收事件和資料。
• 事件類型：
  • NuiSdkTtsEvent：合成任務開始。
  • onTtsDataCallback：返回音訊資料。
  • NuiSdkTtsEvent：合成任務結束。
  • NuiSdkTtsEvent：合成出錯。

使用流程

1. 呼叫 tts_initialize 初始化 SDK，並設定回調介面和連線參數。
2. 呼叫 setParamTts 設定模型、音色和音量等語音合成效果參數。
3. 呼叫 startTts 啟動語音合成任務。
4. 透過 onTtsDataCallback 接收音訊資料。
5. 呼叫 tts_release 釋放 SDK 資源。

Sambert 方法

tts_initialize

初始化語音合成 SDK 執行個體。透過 new NativeNui(Constants.ModeType.MODE_TTS) 建立執行個體，每個執行個體對應一個語音合成通道。同一執行個體在呼叫 tts_release 前禁止重複初始化；如需同時處理多個任務，請建立多個執行個體。

此介面會阻塞呼叫執行緒，請在非 UI 執行緒中呼叫。

方法簽章：

public tts_initialize(callback: NuiTtsSdkListener,
                      ticket: string,
                      level: number,
                      save_log: boolean): number

參數說明：

參數	類型	說明
callback	NuiTtsSdkListener	事件與資料回呼介面的實作。
ticket	string	JSON 字串，包含驗證、連線和偵錯參數。詳見下方 ticket 參數說明。
level	number	控制 SDK 自身日誌的列印層級，取值為 Constants.LogLevel 列舉。
save_log	boolean	是否儲存本機日誌。若為 true，須在 ticket 參數中透過 debug_path 指定路徑，並可透過 max_log_file_size 設定檔案大小。

ticket JSON 範例：

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}

ticket 參數說明：

參數	類型	是否必須	說明
url	string	是	服務地址，固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference。呼叫時請將 {WorkspaceId} 替換為真實的 Workspace ID。
apikey	string	是	API Key。建議使用時效性短、安全性更高的 臨時 API Key，以降低長期有效金鑰洩露的風險。
mode_type	string	是	模式類型。必須設定為字串 "2"，代表線上語音合成模式（對應 Constants.TtsModeTypeCloud）。
device_id	string	是	用於標識終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
debug_path	string	否	日誌檔案的儲存路徑。此參數僅在呼叫 tts_initialize 介面時將 save_log 設為 true 時生效。此時必須設定日誌檔案路徑，否則將報錯。本機最多保留兩個日誌檔案。
max_log_file_size	number	否	設定日誌檔案的最大位元組數。此參數僅在呼叫 tts_initialize 介面時將 save_log 設為 true 時生效。預設值：104857600（100 * 1024 * 1024 位元組，即 100MiB）。

setParamTts

以鍵值對的形式設定語音合成效果參數。在 startTts 之前呼叫。

方法簽章：

public setParamTts(param: string, value: string): number

參數說明：

參數	類型	說明
param	string	參數名稱。
value	string	參數值。

可用參數說明：

參數	類型	是否必須	說明
model	string	是	模型名稱，如 sambert-zhinan-v1。
format	string	否	音訊編碼格式。取值範圍：- pcm - wav - mp3（預設）
volume	string	否	音量。預設值：50。取值範圍：[0, 100]。
sample_rate	string	否	音訊採樣率（Hz）。取值範圍：8000、16000、22050、24000、48000。Sambert 大部分發音人模型預設採樣率為 48000，播放器需按對應採樣率播放。
rate	string	否	語速。預設值：1.0。取值範圍：[0.5, 2.0]。
pitch	string	否	音調。預設值：1.0。取值範圍：[0.5, 2.0]。
word_timestamp_enabled	string	否	是否開啟字級別時間戳記。預設值：false。適用範圍：所有 Sambert 模型。
phoneme_timestamp_enabled	string	否	是否開啟音素級別時間戳記。預設值：false。需要先開啟 word_timestamp_enabled。
enable_audio_decoder	string	否	是否開啟內建音訊解碼器。預設值：0。取值範圍：- 1：開啟。當 format 為 mp3 時，設為 "1" 可開啟 SDK 內建解碼器，此時 onTtsDataCallback 將返回解碼後的 PCM 資料。- 0：關閉。
enable_callback_vol	string	否	是否開啟音量回調。設為 "1" 後啟用 onTtsVolCallback 回調。
apikey	string	否	執行中重新整理臨時 API Key。在合成任務開始前透過 setParamTts('apikey', ...) 注入最新臨時 Key。

getparamTts

取得參數值。主要用於錯誤排查。

方法簽章：

public getparamTts(param: string): string

參數說明：

參數	類型	說明
param	string	參數名稱。目前僅支援 "error_msg"。

傳回值說明：

返回參數值。

startTts

啟動語音合成任務。合成結果透過回調返回。

方法簽章：

public startTts(priority: string, taskid: string, text: string): number

參數說明：

參數	類型	說明
priority	string	任務優先順序。請將其設為 1。
taskid	string	任務 ID。傳入空字串 '' 時由 SDK 自動產生。
text	string	待合成文字。

pauseTts

暫停當前語音合成任務。任務暫停後，可透過 resumeTts 恢復，或透過 cancelTts 徹底取消。在任務暫停期間，SDK 不支援啟動新的合成任務。

注意：此操作僅暫停從服務端的資料拉取，播放器中已快取的音訊資料會繼續播放。

方法簽章：

public pauseTts(): number

resumeTts

恢復處於暫停狀態的語音合成任務。

方法簽章：

public resumeTts(): number

cancelTts

取消合成任務。

注意：此操作僅取消從服務端的資料拉取，播放器中已快取的音訊資料會繼續播放。

方法簽章：

public cancelTts(taskid: string): number

參數說明：

參數	類型	說明
taskid	string	要取消的任務 ID。若傳入空字串 ''，則取消所有正在暫停或進行中的合成任務。

tts_release

釋放 SDK 的所有內部資源，並強制終止所有正在進行的合成任務。呼叫後，SDK 執行個體將不可用；如需再次使用，必須重新呼叫 tts_initialize 進行初始化。

方法簽章：

public tts_release(): number

NuiTtsSdkListener

Sambert 語音合成回調介面，用於接收合成事件和音訊資料。在 HarmonyOS SDK 中，回調介面透過 ArkTS 箭頭函式形式定義。

onTtsEventCallback

監聽語音合成任務的開始、結束、取消、暫停、恢復和錯誤事件。

方法簽章：

onTtsEventCallback: (event: NuiSdkTtsEvent, taskid: string, ret_code: number) => void;

參數說明：

參數	類型	說明
event	NuiSdkTtsEvent	回呼事件。
taskid	string	語音合成任務 ID。
ret_code	number	僅在出現 TTS_EVENT_ERROR 事件時有效。

onTtsDataCallback

監聽語音合成過程中返回的音訊資料和時間戳記資訊。合成期間，SDK 會連續觸發該回調。

方法簽章：

onTtsDataCallback: (info: string, info_len: number, buffer: ArrayBuffer | null) => void;

參數說明：

參數	類型	說明
info	string	JSON 格式的時間戳記結果。word_timestamp_enabled 設為 "1" 時生效。
info_len	number	info 欄位的資料長度，可忽略。
buffer	ArrayBuffer | null	返回當前片段的音訊資料。可能為 null，回調中需判空。

onTtsVolCallback

監聽合成音量。啟用 enable_callback_vol 參數後，該回調返回 SDK 剛收到的合成資料音量，而非當前播放音量。

方法簽章：

onTtsVolCallback: (vol: number) => void;

參數說明：

參數	類型	說明
vol	number	合成資料音量值。

NuiSdkTtsEvent

Sambert 語音合成事件類型列舉。

事件	說明
TTS_EVENT_START	合成任務開始，即將有音訊資料返回。
TTS_EVENT_END	合成任務正常結束，所有音訊資料已透過回調送出。
TTS_EVENT_CANCEL	合成任務已取消。
TTS_EVENT_PAUSE	合成任務已暫停。
TTS_EVENT_RESUME	合成任務已恢復。
TTS_EVENT_ERROR	合成過程中發生錯誤。此時可透過 getparamTts("error_msg") 取得詳細錯誤資訊。{ "header": { "task_id": "xxxxxxxxx", "event": "task-failed", "error_code": "InvalidParameter", "error_message": "Please ensure input text is valid.", "attributes": {} }, "payload": {} }

輔助類型

Constants.LogLevel

level 參數的取值列舉：

值	說明
LOG_LEVEL_VERBOSE	最詳細日誌。
LOG_LEVEL_DEBUG	偵錯日誌。
LOG_LEVEL_INFO	一般資訊日誌（預設）。
LOG_LEVEL_WARNING	警告日誌。
LOG_LEVEL_ERROR	錯誤日誌。
LOG_LEVEL_NONE	關閉日誌。

範例程式碼

1. 取得 API Key： 參見獲取與配置 API Key。建議將 API Key 設定到環境變數中。

   說明當需要為第三方應用程式或使用者提供臨時存取權限，或者希望嚴格控制敏感資料存取、刪除等高風險操作時，建議使用臨時 API Key。臨時 API Key 預設有效期為 60 秒，過期後需重新取得。

2. 下載 SDK 並執行範例程式碼：

   • 下載最新 SDK 整合套件。
   • 解壓縮 TAR 套件。在 neonui 目錄中取得 HAR 格式 SDK，並新增至專案相依性。 若需以 C++ 接入，請使用 TAR 套件內的 native/libs 與 native/include 取得動態連結庫和標頭檔。
   • 使用 DevEco Studio 開啟專案。範例程式碼位於 DashSambertTtsPage.ets 中，替換 API Key 後即可體驗功能。

呼叫步驟

1. 初始化 SDK：呼叫 tts_initialize，傳入 NuiTtsSdkListener 回調與 ticket 參數。
2. 按業務需求設定參數：透過 setParamTts 介面設定模型、格式、採樣率、音色和音量等語音合成效果參數。建議在初始化成功後立即設定。
3. 呼叫 startTts 開始語音合成。
4. 在 onTtsDataCallback 回調中取得音訊資料。建議使用串流播放，詳情請參見下方音訊播放說明。如需儲存到本機，請按附加模式將音訊寫入同一檔案，直至合成完成。
5. 任務結束後，呼叫 tts_release 釋放 SDK 資源。

音訊播放說明

HarmonyOS 透過 @kit.AudioKit 的 AudioRenderer 播放合成音訊。Sambert 合成音訊預設採樣率為 48kHz，因此需將播放器採樣率設定為 48000。

本產品範例已封裝為 AudioPlayer.ets 工具類別，建構時指定採樣率：

// Sambert默认按48000采样率播放（AudioPlayer默认是16000）
this.mAudioPlayer = new AudioPlayer(this, 48000);

播放器透過 writeData 回調從佇列拉取音訊資料，返回 AudioDataCallbackResult.VALID/INVALID。當 onTtsEventCallback 收到 TTS_EVENT_END 後，SDK 已合成完所有資料並透過回調送出，此時應標記播放佇列推送完成，播放器播完剩餘資料後自動停止。