Alibaba Cloud Model Studio：CosyVoice iOS SDK

本文件提供了語音合成CosyVoice iOS SDK的詳細使用指南，協助您將文字轉換為高品質、富有表現力的語音。

NeoNui

架構特點：

• 單例模式：透過 [StreamInputTts get_instance] 取得全域唯一執行個體
• 回呼驅動：透過 StreamInputTtsDelegate 協定接收事件和資料
• JSON 設定：參數透過 JSON 字串傳遞

使用流程

CosyVoice 支援一次性輸入和串流輸入兩種呼叫方式。

一次性輸入：適用於短文字合成、需要使用 SSML 標記語言的場景。

1. playStreamInputTts() 或 asyncPlayStreamInputTts() - 傳送一段完整的待合成文字並開始語音合成。前者為同步請求，合成完成後返回；後者為非同步請求，發起合成後立即返回
2. onStreamInputTtsDataCallback() - 接收音訊資料
3. TTS_EVENT_SYNTHESIS_COMPLETE - 語音合成結束

串流輸入：適用於即時對話、長文字「邊說邊合」的場景。此方式不支援 SSML 標記語言。

1. startStreamInputTts() - 初始化SDK，設定回呼介面和連線參數
2. sendStreamInputTts() - 持續傳送待合成文字
3. onStreamInputTtsDataCallback() - 接收音訊資料
4. stopStreamInputTts() 或 asyncStopStreamInputTts() - 傳送合成結束請求。前者為同步請求，等待合成完成後返回；後者為非同步請求，發起請求後立即返回
5. TTS_EVENT_SYNTHESIS_COMPLETE - 語音合成結束

startStreamInputTts

啟動串流語音合成任務，與伺服器建立連線。

- (int) startStreamInputTts:(const char *)ticket parameters:(const char *)parameters sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

傳回錯誤碼。

ticket JSON範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}

parameters JSON 範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充：

{
  "model": "cosyvoice-v3-plus",
  "voice": "longanyang",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1,
  "pitch": 1,
  "language_hints": ["zh"],
  "enable_ssml": false
}

"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}

sendStreamInputTts

傳送待合成的文字，與 startStreamInputTts 搭配使用。

在呼叫 startStreamInputTts 後，使用此介面持續傳送文字。

所有文字傳送完畢後，需呼叫stopStreamInputTts或asyncStopStreamInputTts來結束傳送。

- (int) sendStreamInputTts:(const char *)text;

傳回錯誤碼。

stopStreamInputTts

同步介面，通知伺服器文字已全部傳送，並阻塞等待所有音訊資料合成並收到 TTS_EVENT_SYNTHESIS_COMPLETE。

封鎖等待的逾時時間由參數 complete_waiting_ms 控制。

- (int) stopStreamInputTts;

傳回錯誤碼。

asyncStopStreamInputTts

非同步介面，通知伺服器端文字已全部傳送。呼叫後立即傳回，合成在背景繼續進行。

透過 TTS_EVENT_SYNTHESIS_COMPLETE 判斷合成是否完成。

- (int) asyncStopStreamInputTts;

傳回錯誤碼。

cancelStreamInputTts

立即中斷與伺服器端的連線並終止目前合成任務。呼叫後不會再收到任何音訊資料回呼。

- (int) cancelStreamInputTts;

傳回錯誤碼。

playStreamInputTts

同步執行的一次性合成介面。該介面會傳送文字並阻塞等待接收所有音訊資料，直到合成完成後才返回。無需再呼叫stopStreamInputTts介面。

該介面預設啟用SSML，可透過parameters中的enable_ssml參數關閉。

- (int) playStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

ticket、parameters等參數與startStreamInputTts介面中的定義相同。

傳回錯誤碼。

asyncPlayStreamInputTts

此介面非同步傳送全部待合成文字。呼叫後立即返回，不等待合成資料。無需再呼叫stopStreamInputTts介面。

該介面預設啟用SSML，可透過parameters中的enable_ssml參數關閉。

- (int) asyncPlayStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

ticket、parameters等參數與startStreamInputTts介面中的定義相同。

傳回錯誤碼。

StreamInputTtsDelegate

CosyVoice 串流語音合成回呼協定，用於接收合成事件、音訊資料和日誌。

onStreamInputTtsEventCallback：監聽事件

- (void)onStreamInputTtsEventCallback:(StreamInputTtsCallbackEvent)event taskId:(char*)taskid sessionId:(char*)sessionId ret_code:(int)ret_code error_msg:(char*)error_msg timestamp:(char*)timestamp all_response:(char*)all_response;

onStreamInputTtsDataCallback：監聽音訊資料

合成過程中，SDK 會連續觸發此回呼，需在回呼中取得音訊資料。

- (void)onStreamInputTtsDataCallback:(char*)buffer len:(int)len;

onStreamInputTtsLogTrackCallback：監聽追蹤日誌

此回調用於接收 SDK 內部的詳細日誌，方便進行問題定位和偵錯。

- (void)onStreamInputTtsLogTrackCallback:(NuiSdkLogLevel)level
                            logMessage:(const char *)log;

StreamInputTtsCallbackEvent

CosyVoice 串流語音合成事件類型列舉。

{
  "header": {
      "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
      "event": "task-failed",
      "error_code": "InvalidParameter",
      "error_message": "[tts:]Engine return error code: 418",
      "attributes": {}
  },
  "payload": {}
}

NuiSdkLogLevel

SDK 日誌層級列舉，用於控制日誌輸出。

範例程式碼

1. 取得API Key：取得與設定 API Key。

2. 下載 SDK 並執行範例程式碼：
   • 下載最新SDK整合包。
   • 解壓縮 ZIP 套件，將其中的 nuisdk.framework 新增至專案。
   • 在 Build Phases → Link Binary With Libraries 中新增 nuisdk.framework。
   • 在 General → Frameworks, Libraries, and Embedded Content 中將 nuisdk.framework 設定為 Embed & Sign。
   • 使用 Xcode 開啟範例專案。範例程式碼位於DashCosyVoiceStreamInputTTSViewController.m，替換 API Key 後體驗功能。

呼叫方式

進階功能

SSML 標記語言

目的：透過在文字中嵌入 XML 標籤，實現對發音、語速、停頓等細節的精確控制。

使用限制：僅支援一次性輸入待合成文字（playStreamInputTts 或 asyncPlayStreamInputTts 介面），不支援串流輸入待合成文字（sendStreamInputTts介面）。

使用方法：呼叫 playStreamInputTts 或 asyncPlayStreamInputTts 介面時，SDK 會自動啟用 SSML，此時直接在 text 參數中傳入包含 SSML 標籤的文字即可。

更多說明請參閱 SSML 與 LaTeX。

數學運算式

目的：使模型能夠正確朗讀常見的數學公式和運算式。

使用方法：直接在 text 參數中傳入包含 LaTeX 格式的數學運算式的文字即可。更多說明請參見 LaTeX 公式轉語音。