Skip to main content

Qwen-Audio-TTS / CosyVoice Flutter SDK

Qwen-Audio-TTS / CosyVoice 的 Flutter SDK 接入指南,包含 Dart 呼叫流程、請求參數和事件。

Qwen-Audio-TTS 和 CosyVoice 共用雙向串流介面。應用程式可在分段傳送文字的同時接收合成音訊。

先決條件

  • 為目標平台設定 Flutter 開發環境。範例專案需要 Dart 3.4 以上、低於 4.0 的版本。
  • 取得 API Key。選擇與 API Key 位於相同地區的服務端點。若使用工作空間專屬網域,請一併取得業務空間 ID。
請勿在行動應用程式的程式碼中寫入長期 API Key。對於支援臨時 API Key 的模型,請由應用程式伺服器產生臨時 API Key,再傳送給用戶端。

安裝 SDK

開啟行動裝置語音 SDK 選型與下載,在 Flutter 分頁下載並解壓縮整合包。 將解壓縮後的 SDK 目錄複製到 Flutter 專案中的 packages/aliyun_neonui,並在 pubspec.yaml 中加入本機相依性。
dependencies:
  aliyun_neonui:
    path: packages/aliyun_neonui
執行 flutter pub get,再於 Dart 檔案中匯入 SDK。
import 'package:aliyun_neonui/neonui.dart';

快速入門

執行範例應用程式

  1. 連接目標裝置,在解壓縮後的 SDK 目錄中執行下列命令。
    cd example
    flutter pub get
    flutter run
    
  2. 在範例應用程式首頁開啟 百炼(DashScope)。選擇服務端點並填寫 API Key。若使用工作空間專屬網域,也請填寫 WorkspaceId。
  3. 開啟 Qwen-Audio-TTS/CosyVoice 双向流式语音合成 並執行範例。
完整範例位於整合包的 example/lib/pages/dashscope/dash_cosy_voice_stream_tts_page.dart。

整合包範例提供的模型

  • qwen-audio-3.1-tts-flash
  • qwen-audio-3.1-tts-plus
  • qwen-audio-3.0-tts-flash
  • qwen-audio-3.0-tts-plus
  • cosyvoice-v3-flash
  • cosyvoice-v3-plus

呼叫步驟

透過 NativeNui() 取得執行個體後,即可呼叫下列方法。
  1. 先訂閱 streamTtsEventStream 和 streamTtsAudioStream,再呼叫下列方法。
  2. 下方使用請求參數中的連線 JSON 和任務 JSON 作為 ticketJson 和 paramsJson。
    await nui.streamTtsStart(ticket: ticketJson, params: paramsJson);
    await nui.streamTtsSend('你好,');
    await nui.streamTtsSend('欢迎使用语音合成。');
    
    啟動合成後分段傳送文字,並播放音訊串流傳回的音訊。
  3. 使用 streamTtsStop 結束文字輸入。收到合成完成事件後呼叫 streamTtsRelease。

請求參數

下例使用整合包內的一個模型。其他設定請見整合包內的 example/lib/dashscope_params.dart。更多參數說明請參閱Android SDK、iOS SDK、HarmonyOS SDK。 將 YOUR_WS_HOST 取代為所在區域的 WebSocket 主機名稱、YOUR_DEVICE_ID 取代為裝置識別碼,並填寫該區域的 YOUR_API_KEY。

連線參數

將連線 JSON 作為 ticket 傳入。
{
  "apikey": "YOUR_API_KEY",
  "device_id": "YOUR_DEVICE_ID",
  "url": "wss://YOUR_WS_HOST/api-ws/v1/inference"
}

任務參數

將範例 JSON 當成字串傳入 Dart 方法。
{
  "model": "qwen-audio-3.1-tts-flash",
  "voice": "longanhuan_v3.1",
  "format": "pcm",
  "enable_audio_decoder": false,
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1.0,
  "pitch": 1.0
}
voice 必須與 model 相容。format 和 sample_rate 定義輸出格式和取樣率。範例選擇 MP3 或 Opus 時會啟用 enable_audio_decoder。

API 參考

方法

回傳 Future<int> 的方法以結果碼 0 表示成功。
方法簽名用途
Future<int> streamTtsStart({required String ticket, required String params, String sessionId = "", int logLevel = 0, bool saveLog = false})建立串流合成工作階段,將 ticket 和 params 各以 JSON 字串傳入。
Future<int> streamTtsSend(String text)繼續傳送下一段文字。
Future<int> streamTtsStop({bool flagAsync = true})結束文字輸入。flagAsync 預設為 true,使用非同步停止。
Future<int> streamTtsAsyncPlay({required String ticket, required String params, required String text, String sessionId = "", int logLevel = 0, bool saveLog = false})一次提交完整文字,非同步接收合成結果。
Future<int> streamTtsCancel()取消目前的工作階段或合成。
Future<int> streamTtsRelease()釋放 SDK 資源。

事件與音訊串流

透過 streamTtsEventStream 接收事件。事件以 Dart Map 傳回時,使用 event 判斷事件名稱,並透過 resultCode 查看任務錯誤。 音訊串流 streamTtsAudioStream 傳回音訊片段,由應用程式播放。
事件用途
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED合成或回覆音訊開始
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS句級合成事件
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE任務或目前音訊輸出完成
STREAM_INPUT_TTS_EVENT_TASK_FAILED任務失敗