Alibaba Cloud Model Studio：Qwen-Audio-TTS Android SDK

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

NativeNui

本 SDK 支援建立多個 NativeNui 執行個體，並透過回呼機制處理語音合成事件。

架構特點：

• 多例模式：透過 new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS) 建立執行個體

• 回呼驅動：透過 INativeStreamInputTtsCallback 介面接收事件和資料

• 事件類型：
  • STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED：合成任務開始
  • onStreamInputTtsDataCallback：音訊資料傳回
  • STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE：合成任務結束
  • STREAM_INPUT_TTS_EVENT_TASK_FAILED：合成出錯

使用流程

Qwen-Audio-TTS 支援一次性輸入和串流輸入兩種呼叫方式。

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

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

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

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

startStreamInputTts

啟動雙向串流語音合成，建立與伺服器端的連線，並註冊回呼以接收事件和音訊資料。

此介面可能會引起阻塞，應在非UI執行緒呼叫。

public synchronized int startStreamInputTts(INativeStreamInputTtsCallback callback,
                                            String ticket,
                                            String parameters,
                                            String session_id,
                                            int log_level,
                                            boolean save_log)

傳回錯誤碼。

ticket JSON 範例：

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

parameters JSON 範例：

{
    "model": "qwen-audio-3.0-tts-flash",
    "voice": "longanlingxi",
    "format": "mp3",
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
}

parameters 參數說明：

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

sendStreamInputTts

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

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

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

public synchronized int sendStreamInputTts(String text)

傳回錯誤碼。

stopStreamInputTts

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

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

public synchronized int stopStreamInputTts()

傳回錯誤碼。

asyncStopStreamInputTts

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

透過 STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE 事件判斷合成是否完成。

public synchronized int asyncStopStreamInputTts()

傳回錯誤碼。

cancelStreamInputTts

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

public synchronized int cancelStreamInputTts()

傳回錯誤碼。

playStreamInputTts

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

此介面預設啟用 SSML。如果明確設定 enable_ssml，則以使用者設定為準。

此介面應在非UI執行緒呼叫。

public synchronized int playStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)

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

傳回錯誤碼。

asyncPlayStreamInputTts

非同步執行的一次性合成介面。呼叫後立即傳回，合成任務在背景進行，結果透過回呼傳回。無需再呼叫 stop 介面。

此介面預設啟用 SSML。如果明確設定 enable_ssml，則以使用者設定為準。

public synchronized int asyncPlayStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)

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

傳回錯誤碼。

INativeStreamInputTtsCallback

Qwen-Audio-TTS 串流語音合成回呼介面，用於接收合成事件、音訊資料和日誌。

onStreamInputTtsEventCallback：監聽事件

void onStreamInputTtsEventCallback(StreamInputTtsEvent event,
                                   String task_id,
                                   String session_id,
                                   int ret_code,
                                   String error_msg,
                                   String timestamp,
                                   String all_response);

onStreamInputTtsDataCallback：監聽音訊資料

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

void onStreamInputTtsDataCallback(byte[] data);

onStreamInputTtsLogTrackCallback：監聽追蹤日誌

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

default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent

Qwen-Audio-TTS 串流語音合成事件類型列舉。

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

範例程式碼

1. 取得 API Key：取得與設定 API Key，為安全起見，建議將 API Key 設定至環境變數。

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

2. 下載 SDK 並執行範例程式碼：
   • 下載最新SDK整合包。
   • 解壓縮 ZIP 套件。在 app/libs 目錄中取得 AAR 格式 SDK，並新增至專案相依性。
     需要 Android CPP 接入時，使用 ZIP 套件內的 android_libs 與 android_include 取得動態連結庫和標頭檔。
     
   • 使用 Android Studio 開啟專案。範例程式碼位於 DashCosyVoiceStreamTtsActivity.java，替換 API Key 後體驗功能。

呼叫方式

進階功能

SSML 標記語言

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

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

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

更多說明請參閱 SSML 與 LaTeX。

數學運算式

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

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