Sambert 的 Flutter SDK 接入指南,包含 Dart 呼叫流程、請求參數和事件。
Sambert 使用單向串流介面。應用程式一次提交完整文字,再分段接收合成音訊。
先決條件
- 為目標平台設定 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';
快速入門
執行範例應用程式
-
連接目標裝置,在解壓縮後的 SDK 目錄中執行下列命令。
cd example flutter pub get flutter run -
在範例應用程式首頁開啟 百炼(DashScope)。選擇服務端點並填寫 API Key。若使用工作空間專屬網域,也請填寫 WorkspaceId。
-
開啟 Sambert 单向流式语音合成 並執行範例。
完整範例位於整合包的 example/lib/pages/dashscope/dash_sambert_tts_page.dart。
整合包範例提供的模型
sambert-zhinan-v1
呼叫步驟
透過 NativeNui() 取得執行個體後,即可呼叫下列方法。
-
先訂閱
ttsEventStream和ttsAudioStream,再呼叫下列方法。 -
下方使用請求參數中的連線 JSON 作為
initJson。以鍵值組的方式將任務參數傳給ttsSetParam。await nui.ttsInitialize(params: initJson); for (final entry in taskParams.entries) { await nui.ttsSetParam(entry.key, entry.value); } await nui.ttsStart(priority: '1', taskId: '', text: '你好,欢迎使用语音合成。');初始化後逐項設定任務參數。使用
ttsStart提交完整文字,再從音訊串流取得傳回的音訊。 -
收到
TTS_EVENT_END後仍可處理已收到的音訊。用完後呼叫ttsRelease。
請求參數
下例使用整合包內的一個模型。其他設定請見整合包內的 example/lib/dashscope_params.dart。
將 YOUR_WS_HOST 取代為所在區域的 WebSocket 主機名稱、YOUR_DEVICE_ID 取代為裝置識別碼,並填寫該區域的 YOUR_API_KEY。
連線參數
將範例 JSON 當成字串傳入 Dart 方法。
{
"url": "wss://YOUR_WS_HOST/api-ws/v1/inference",
"device_id": "YOUR_DEVICE_ID",
"mode_type": "2"
}
任務參數
使用 ttsSetParam(key, value) 逐項設定任務參數。數值也請依範例使用字串。
{
"apikey": "YOUR_API_KEY",
"model": "sambert-zhinan-v1",
"format": "pcm",
"enable_audio_decoder": "0",
"sample_rate": "48000",
"volume": "50",
"rate": "1.0",
"pitch": "1.0"
}
Sambert 以 model 設定音色對應的模型 ID。下例採用整合包內的 48 kHz 音色,播放時請使用相同取樣率。
API 參考
方法
回傳 Future<int> 的方法以結果碼 0 表示成功。
| 方法簽名 | 用途 |
|---|---|
Future<int> ttsInitialize({required String params, int logLevel = 0, bool saveLog = false}) | 以 JSON 字串傳入連線參數並初始化 SDK。 |
Future<int> ttsSetParam(String key, String value) | 逐項設定字串參數。 |
Future<int> ttsStart({required String priority, required String taskId, required String text}) | 提交完整待合成文字。範例使用 priority: '1' 及 taskId: ''。 |
Future<int> ttsPause() | 暫停合成。 |
Future<int> ttsResume() | 繼續合成。 |
Future<int> ttsCancel(String taskId) | 以任務 ID 取消合成。 |
Future<String?> ttsGetParam(String key) | 讀取指定參數。使用 error_msg 查看錯誤詳情。 |
Future<int> ttsRelease() | 釋放 SDK 資源。 |
事件與音訊串流
透過 ttsEventStream 接收事件。事件以 Dart Map 傳回時,使用 event 判斷事件名稱,並透過 resultCode 查看任務錯誤。
音訊串流 ttsAudioStream 傳回音訊片段,由應用程式播放。
| 事件 | 用途 |
|---|---|
TTS_EVENT_START | 合成或回覆音訊開始 |
TTS_EVENT_END | 任務或目前音訊輸出完成 |
TTS_EVENT_CANCEL | 任務已取消 |
TTS_EVENT_ERROR | 任務失敗 |