リアルタイム音声合成用の HarmonyOS SDK の統合、パラメーター、API、コールバック、およびサンプルコードについて説明します。
NativeNui
HarmonyOS SDKは、NativeNui を通じてストリーミングテキスト読み上げを提供します。
new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS)を呼び出して、ストリーミングテキスト読み上げインスタンスを作成します。NativeNui.GetInstance()はMODE_DIALOGシングルトンを返すため、ストリーミングテキスト読み上げには使用できません。- ストリーミングテキスト読み上げモードでは
initialize()を呼び出さないでください。認証情報と合成パラメーターを直接startStreamInputTts()、playStreamInputTts()、またはasyncPlayStreamInputTts()に渡してください。 INativeStreamInputTtsCallbackを通じて合成イベントと音声を受信します。- SDK は、タスク開始時に
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDを返し、onStreamInputTtsDataCallbackを通じて音声を返し、タスク終了時にSTREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEを返し、合成失敗時にSTREAM_INPUT_TTS_EVENT_TASK_FAILEDを返します。
呼び出しフロー
Qwen-Audio-TTS は一括入力とストリーミング入力をサポートしています。
一括入力は、短いテキストやSSMLが必要なシナリオに適しています。
playStreamInputTtsまたはasyncPlayStreamInputTtsを呼び出して、完全なテキストを渡し、合成を開始します。前者は合成が完了するまでブロックします。後者はすぐに戻り、バックグラウンドで合成を行います。最初にstartStreamInputTtsを呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。onStreamInputTtsDataCallbackで音声を受信します。STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEを受信すると合成が終了します。
startStreamInputTtsを呼び出して接続を開き、コールバックとパラメータを設定します。sendStreamInputTtsを呼び出してテキストフラグメントを送信します。onStreamInputTtsDataCallbackで音声を受信します。- すべてのテキストが送信された後、
stopStreamInputTtsを呼び出します。 STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEを受信すると合成が終了します。
releaseStreamInputTts を呼び出してリソースを解放してください。
単一のテキスト入力の長さと、複数の入力の累積長の両方に制限があります。Qwen-Audio-TTS WebSocket APIを参照してください。
startStreamInputTts
双方向ストリーミング合成を開始し、接続を開き、コールバックを登録します。このメソッドはブロックされる可能性があります。UI スレッドでは呼び出さないでください。
| パラメータ | タイプ | 説明 |
|---|---|---|
callback | INativeStreamInputTtsCallback | イベントおよび音声コールバック。 |
ticket | string | 認証、接続、およびデバッグ設定を含む JSON 文字列。 |
parameters | string | 合成設定を含む JSON 文字列。 |
session_id | string | クライアント指定のセッション ID。サーバーに生成させる場合は、空の文字列を渡してください。 |
log_level | number | SDK ログレベル。 Constants.LogLevel 値: 0 (VERBOSE)、1 (DEBUG)、2 (INFO)、3 (WARNING)、4 (ERROR)、または 5 (NONE)。 |
save_log | boolean | ログをローカルに保存するかどうか。 trueに設定した場合は、 debug_path 内の ticket. |
Constants.NuiResultCode.SUCCESS (0) は成功を示します。
ticket フィールド
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
url | string | はい | サービスエンドポイント。パブリックエンドポイント wss://dashscope.aliyuncs.com/api-ws/v1/inference、またはワークスペース固有のエンドポイント: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference(北京用)または wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference(シンガポール用)を使用します。 {WorkspaceId} をお使いの ワークスペースID. |
apikey | string | はい | API キー。 一時的な API キー を使用して、長期キーが露出するリスクを軽減します。 |
device_id | string | はい | アプリ内ユーザーIDやクライアント生成のデバイスIDなど、一意のエンドユーザー識別子です。主にログのトレースとトラブルシューティングに使用されます。 |
complete_waiting_ms | number | いいえ | 合成完了イベントを待機する時間 (ミリ秒)。 stopStreamInputTts(false)。デフォルト: 10000. |
debug_path | string | いいえ | ログディレクトリ。このフィールドは、 save_log は true。SDKは最大2つのログファイルを保持します。 |
max_log_file_size | number | いいえ | 1つのログファイルの最大サイズ(バイト単位)。デフォルト: 104857600 (100 MiB) の場合にのみ有効です。 save_log は true. |
log_track_level | number | いいえ | 内部トレースログフィルターレベル。デフォルト: 2。有効な値は log_levelと同じです。HarmonyOS コールバックインターフェースは現在ストリーミング TTS ログコールバックを公開していないため、フィルター処理されたログは SDK によってのみ書き込まれます。 |
parameters フィールド
| フィールド | タイプ | 必須 | 説明 |
|---|---|---|---|
model | string | はい | モデル名。 音声合成モデル. |
voice | string | はい | 音声。システム音声については、 Qwen-Audio-TTS の音声を参照してください。音声クローンまたは ボイスデザイン. |
format | string | いいえ | 音声エンコード形式: pcm, wav, mp3 (デフォルト)、または opus. |
enable_audio_decoder | boolean | いいえ | SDK デコーダーを有効にするかどうか。デフォルト: false。MP3 または Opus の場合、これを true に設定して、データコールバックを通じて返される前に音声を PCM にデコードします。 |
volume | number | いいえ | 音量。デフォルト: 50。有効な範囲: [0, 100]. |
sample_rate | number | いいえ | サンプリングレート (Hz)。有効な値: 8000, 16000, 22050 (デフォルト)、 24000, 44100、および 48000. |
rate | number | いいえ | 話速。デフォルト: 1.0。有効な範囲: [0.5, 2.0]. |
pitch | number | いいえ | ピッチ。デフォルト: 1.0。有効な範囲: [0.5, 2.0]. |
bit_rate | number | いいえ | MP3 または Opus のビットレート (kbps)。デフォルト: 32。有効な範囲: [6, 510]. |
enable_ssml | boolean | いいえ | SSML を有効にするかどうか。デフォルト: false。 SSML の制限事項. |
word_timestamp_enabled | boolean | いいえ | ワードレベルのタイムスタンプを返すかどうか。デフォルト: false。このフィールドはストリーミング出力でのみ使用可能です。クローン音声に対応しています。対応するシステム音声については、Qwen-Audio-TTS の音声リストをご参照ください。タイムスタンプの結果は all_response の INativeStreamInputTtsCallback. |
seed | number | いいえ | 合成結果を変化させるために使用されるランダムシード。モデルバージョン、テキスト、音声、および他のすべてのパラメーターが同じ場合、同じ seed で同じ結果が再現されます。デフォルト: 0。有効な範囲: [0, 65535]. |
language_hints | string[] | いいえ | 合成対象言語。この設定は合成を改善し、音声クローンに使用されるサンプル音声の言語とは独立しています。音声クローンタスクのソース言語を設定するには、音声クローン API リファレンスを参照してください。現在のバージョンでは最初の配列要素のみが使用されるため、値を 1 つ渡してください。数字、略語、または記号の読み上げが予期しないものである場合、またはあまり一般的でない言語での合成が不自然な場合に、このフィールドを使用します。たとえば、 "hello, this is 110" を中国語の読み方ではなく英語で「one one zero」と読み上げたり、 @ を「at」と読み上げたりすることができます。
有効な値
|
instruction | string | いいえ | 方言、感情、または役割を制御する指示。 指示制御. |
enable_aigc_tag | boolean | いいえ | 不可視の AIGC タグを埋め込むかどうか。デフォルト: false。 |
aigc_propagator | string | いいえ | ContentPropagator フィールド。 enable_aigc_tag は trueの場合にのみ有効になります。デフォルト: Alibaba Cloud UID。サポートされているモデルは enable_aigc_tag. |
aigc_propagate_id | string | いいえ | PropagateID フィールド。 enable_aigc_tag は trueと同じです。デフォルト: 現在のリクエスト ID。サポートされているモデルは enable_aigc_tag. |
hot_fix | object | いいえ | カスタム発音とテキスト置換のためのテキストホットフィックス設定。 スキーマについては、 クライアントイベント. |
sendStreamInputTts
startStreamInputTts が成功した後にテキストフラグメントを送信します。このメソッドは SSML タグを解析しません。すべてのテキストを送信した後、stopStreamInputTts() を呼び出してください。
| パラメータ | タイプ | 説明 |
|---|---|---|
text | string | 合成するテキスト。 SSML はサポートされていません。SSML タグは通常のテキストとして読み上げられます。 |
stopStreamInputTts
true(デフォルト): 非同期に終了し、すぐに戻ります。合成が完了したことを確認するには、STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEを待機してください。false: すべての音声と合成完了イベントを受信するまでブロックします。タイムアウトはcomplete_waiting_msによって制御されます。
| パラメータ | タイプ | 説明 |
|---|---|---|
flag_async | boolean | 非同期に終了するかどうか。デフォルト: true. true はサーバーの応答を待たずに戻ります。 false は合成が完了するまでブロックします。 |
cancelStreamInputTts
cancelStreamInputTtsKeepConnection
playStreamInputTts
startStreamInputTts を呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。SSML はデフォルトで有効になっています。enable_ssml が明示的に設定されている場合、その値が優先されます。このメソッドを UI スレッドで呼び出さないでください。
callback、ticket、parameters、session_id、log_level、および save_log は startStreamInputTts で定義されています。text は合成するテキストであり、SSML をサポートしています。このメソッドはエラーコード を返します。
asyncPlayStreamInputTts
startStreamInputTts を呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。SSML はデフォルトで有効になっています。enable_ssml が明示的に設定されている場合、その値が優先されます。
callback、ticket、parameters、session_id、log_level、および save_log は startStreamInputTts で定義されています。text は合成するテキストであり、SSML をサポートしています。このメソッドはエラーコード を返します。
releaseStreamInputTts
INativeStreamInputTtsCallback
onStreamInputTtsEventCallback
| パラメータ | タイプ | 説明 |
|---|---|---|
event | StreamInputTtsEvent | 合成イベント。 |
task_id | string | 合成タスク ID。 |
session_id | string | セッション ID。クライアント指定の値は変更されずに返されます。それ以外の場合、サーバーが生成します。 |
ret_code | number | エラーコード。タスク失敗イベントに対してのみ有効です。 |
error_msg | string | エラーメッセージ。タスク失敗イベントに対してのみ有効です。 |
timestamp | string | タイムスタンプ結果。 |
all_response | string | サーバーからの完全な応答 (JSON 文字列)。使用法、タイムスタンプ、およびエラーの詳細についてはこれを解析してください。 |
onStreamInputTtsDataCallback
- MP3 および Opus データにはストリーミングデコーダーが必要です。あるいは、
enable_audio_decoderをtrueに設定して、SDK が PCM を返すようにすることもできます。 - 完全なファイルを組み立てるには、コールバックデータを順番に追加します。
- WAV および MP3 の場合、ファイルヘッダーが含まれるのは最初のコールバックのみです。各 Opus フレームは独立した Ogg ページであり、順番に連結できます。
StreamInputTtsEvent
| イベント | 説明 |
|---|---|
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED | サーバーがリクエストを受け入れ、処理を開始しました。最初の音声データは通常、このイベントの直後に onStreamInputTtsDataCallback を通じて到着します。 |
STREAM_INPUT_TTS_EVENT_SENTENCE_BEGIN | サーバーが発話の合成を開始しました。 |
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS | 課金情報とタイムスタンプを含む合成の進行状況情報。 |
STREAM_INPUT_TTS_EVENT_SENTENCE_END | サーバーが発話の合成を完了しました。 |
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE | サーバーがすべてのオーディオデータを返しました。 onStreamInputTtsEventCallback このイベント後に呼び出されることはなく、これが明示的なストリーム終了シグナルとなります。このイベントは、ローカル再生が完了したことを示すものではありません。 |
STREAM_INPUT_TTS_EVENT_TASK_FAILED | 合成に失敗しました。 task_id, error_code、および error_message から all_response、または ret_code および error_msg コールバック引数を使用します。 |
サンプルコード
- APIキーを取得します。クライアントアプリケーションに長期間有効なAPIキーをハードコードしないでください。アプリケーションサーバーで一時的なAPIキーを取得し、クライアントに送信することをお勧めします。
- 最新のSDKパッケージをダウンロードします。パッケージを抽出し、
entry/libs/neonui.harをアプリケーションのentry/libsディレクトリにコピーし、entry/oh-package.json5に依存関係を追加します。
- DevEco StudioでSDKパッケージのサンプルプロジェクトを開きます。サンプルページは
entry/src/main/ets/pages/dashscope/DashCosyVoiceStreamTtsPage.etsです。APIキーを設定してプロジェクトを実行します。
DashCosyVoiceStreamTtsPage.ets を参照してください。
playStreamInputTts または asyncPlayStreamInputTts を呼び出します。
高度な機能
SSML
目的:テキストにXMLタグを埋め込んで、発音、話速、ポーズ、その他の合成の詳細を制御します。
制限事項: SSML をサポートしているのは、一括入力 API の playStreamInputTts と asyncPlayStreamInputTts のみです。ストリーミング入力 API の sendStreamInputTts はサポートしていません。
使用方法: SDK は playStreamInputTts および asyncPlayStreamInputTts に対してデフォルトで SSML を有効にします。SSML テキストを text に渡してください。詳細については、SSML と LaTeXを参照してください。
数式
目的:モデルに一般的な数式や表現を正しく読み上げさせます。
使用方法: LaTeX 形式の数式を含むテキストを text に渡します。サポートされている構文については、LaTeX テキスト読み上げを参照してください。