CosyVoice HarmonyOS SDK - Alibaba Cloud Model Studio - Alibaba Cloud ドキュメントセンター

リアルタイム音声合成用の 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 を返します。

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);

呼び出しフロー

CosyVoice は一括入力とストリーミング入力をサポートしています。

一括入力は、短いテキストやSSMLが必要なシナリオに適しています。

playStreamInputTts または asyncPlayStreamInputTts を呼び出して、完全なテキストを渡し、合成を開始します。前者は合成が完了するまでブロックします。後者はすぐに戻り、バックグラウンドで合成を行います。最初に startStreamInputTts を呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。
onStreamInputTtsDataCallback で音声を受信します。
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE を受信すると合成が終了します。

ストリーミング入力は、リアルタイムの会話や長いテキストの増分合成に適しています。このモードでは SSML はサポートされていません。

startStreamInputTts を呼び出して接続を開き、コールバックとパラメータを設定します。
sendStreamInputTts を呼び出してテキストフラグメントを送信します。
onStreamInputTtsDataCallback で音声を受信します。
すべてのテキストが送信された後、stopStreamInputTts を呼び出します。
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE を受信すると合成が終了します。

テキスト読み上げが不要になったら、releaseStreamInputTts を呼び出してリソースを解放してください。

単一のテキスト入力の長さと、複数の入力の累積長の両方に制限があります。CosyVoice WebSocket APIを参照してください。

startStreamInputTts

双方向ストリーミング合成を開始し、接続を開き、コールバックを登録します。このメソッドはブロックされる可能性があります。UI スレッドでは呼び出さないでください。

startStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

パラメータ	タイプ	説明
`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": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}

フィールド	タイプ	必須	説明
`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": "cosyvoice-v3-plus",
  "voice": "longanyang",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1.0,
  "pitch": 1.0,
  "enable_audio_decoder": true
}

フィールド	タイプ	必須	説明
`model`	`string`	はい	モデル名。音声合成モデル.
`voice`	`string`	はい	音声。システム音声については、 CosyVoice の音声を参照してください。音声クローンまたはボイスデザイン.
`format`	`string`	いいえ	音声エンコード形式: `pcm`, `wav`, `mp3` (デフォルト)、または `opus`. 注記`cosyvoice-v1` は 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]`. 注記`cosyvoice-v1` はこのフィールドをサポートしていません。
`enable_ssml`	`boolean`	いいえ	SSML を有効にするかどうか。デフォルト: `false`。 SSML の制限事項.
`word_timestamp_enabled`	`boolean`	いいえ	ワードレベルのタイムスタンプを返すかどうか。デフォルト: `false`。このフィールドはストリーミング出力でのみ使用可能です。注記cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 のクローン音声、および CosyVoice の音声リストでサポートされているとマークされたシステム音声をサポートしています。他のモデルのクローン音声はサポートされていません。タイムスタンプの結果は `all_response` の `INativeStreamInputTtsCallback`.
`seed`	`number`	いいえ	合成結果を変化させるために使用されるランダムシード。モデルバージョン、テキスト、音声、および他のすべてのパラメーターが同じ場合、同じ `seed` で同じ結果が再現されます。デフォルト: `0`。有効な範囲： `[0, 65535]`. 注記`cosyvoice-v1` はこのフィールドをサポートしていません。
`language_hints`	`string[]`	いいえ	合成対象言語。この設定は合成を改善し、音声クローンに使用されるサンプル音声の言語とは独立しています。音声クローンタスクのソース言語を設定するには、音声クローン API リファレンスを参照してください。現在のバージョンでは最初の配列要素のみが使用されるため、値を 1 つ渡してください。数字、略語、または記号の読み上げが予期しないものである場合、またはあまり一般的でない言語での合成が不自然な場合に、このフィールドを使用します。たとえば、 `"hello, this is 110"` を中国語の読み方ではなく英語で「one one zero」と読み上げたり、 `@` を「at」と読み上げたりすることができます。有効な値サポートされている値: `zh`, `en`, `fr`, `de`, `ja`, `ko`, `ru`, `pt`, `th`, `id`, `vi`, `es`, `it`, `ms`, `fil`、および `ar`. 注記`cosyvoice-v1` はこのフィールドをサポートしていません。
`instruction`	`string`	いいえ	方言、感情、または役割を制御する指示。指示制御.
`enable_aigc_tag`	`boolean`	いいえ	不可視の AIGC タグを埋め込むかどうか。デフォルト: `false`。注記cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 でサポートされています。
`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`	いいえ	カスタム発音とテキスト置換のためのテキストホットフィックス設定。注記`cosyvoice-v2` および `cosyvoice-v1` はこのフィールドをサポートしていません。スキーマについては、クライアントイベント.

sendStreamInputTts

sendStreamInputTts(text: string): number

startStreamInputTts が成功した後にテキストフラグメントを送信します。このメソッドは SSML タグを解析しません。すべてのテキストを送信した後、stopStreamInputTts() を呼び出してください。

パラメータ	タイプ	説明
`text`	`string`	合成するテキスト。 SSML はサポートされていません。SSML タグは通常のテキストとして読み上げられます。

このメソッドはエラーコードを返します。

stopStreamInputTts

stopStreamInputTts(flag_async: boolean = true): number

ストリーミング入力を終了します。

true (デフォルト): 非同期に終了し、すぐに戻ります。合成が完了したことを確認するには、STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE を待機してください。
false: すべての音声と合成完了イベントを受信するまでブロックします。タイムアウトは complete_waiting_ms によって制御されます。

同期停止の後にキャンセルメソッドを呼び出すとブロックされる可能性があります。デフォルトの非同期モードを推奨します。

パラメータ	タイプ	説明
`flag_async`	`boolean`	非同期に終了するかどうか。デフォルト: `true`. `true` はサーバーの応答を待たずに戻ります。 `false` は合成が完了するまでブロックします。

このメソッドはエラーコードを返します。

cancelStreamInputTts

cancelStreamInputTts(): number

即座に接続を閉じ、現在のタスクを終了します。この呼び出し以降、音声コールバックは受信されません。このメソッドはエラーコードを返します。

cancelStreamInputTtsKeepConnection

cancelStreamInputTtsKeepConnection(): number

プロトコルレベルのキャンセルコマンドを送信して現在のタスクを終了しますが、WebSocket 接続は開いたままにします。接続を再開するコストを回避して、別の合成ラウンドをすぐに開始する必要がある場合にこのメソッドを使用します。このメソッドはエラーコードを返します。

playStreamInputTts

playStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

同期一括合成。このメソッドはタスクを初期化し、テキストを送信し、すべての音声を受信してから戻ります。最初に startStreamInputTts を呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。SSML はデフォルトで有効になっています。enable_ssml が明示的に設定されている場合、その値が優先されます。このメソッドを UI スレッドで呼び出さないでください。

callback、ticket、parameters、session_id、log_level、および save_log は startStreamInputTts で定義されています。text は合成するテキストであり、SSML をサポートしています。このメソッドはエラーコードを返します。

asyncPlayStreamInputTts

asyncPlayStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

非同期一括合成。このメソッドはすぐに戻り、コールバックを通じて結果を配信します。最初に startStreamInputTts を呼び出さないでください。また、その後で stop メソッドを呼び出さないでください。SSML はデフォルトで有効になっています。enable_ssml が明示的に設定されている場合、その値が優先されます。

releaseStreamInputTts

releaseStreamInputTts(): number

ストリーミング TTS インスタンスとそのリソースを解放します。ページが破棄されたとき、またはテキスト読み上げが不要になったときにこのメソッドを呼び出してください。このメソッドはエラーコードを返します。

INativeStreamInputTtsCallback

export interface INativeStreamInputTtsCallback {
  onStreamInputTtsEventCallback(
    event: StreamInputTtsEvent,
    task_id: string,
    session_id: string,
    ret_code: number,
    error_msg: string,
    timestamp: string,
    all_response: string
  ): void;

  onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;
}

onStreamInputTtsEventCallback

パラメータ	タイプ	説明
`event`	`StreamInputTtsEvent`	合成イベント。
`task_id`	`string`	合成タスク ID。
`session_id`	`string`	セッション ID。クライアント指定の値は変更されずに返されます。それ以外の場合、サーバーが生成します。
`ret_code`	`number`	エラーコード。タスク失敗イベントに対してのみ有効です。
`error_msg`	`string`	エラーメッセージ。タスク失敗イベントに対してのみ有効です。
`timestamp`	`string`	タイムスタンプ結果。
`all_response`	`string`	サーバーからの完全な応答 (JSON 文字列)。使用法、タイムスタンプ、およびエラーの詳細についてはこれを解析してください。

onStreamInputTtsDataCallback

onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;

音声フラグメントを継続的に返します。次の点に注意してください。

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` コールバック引数を使用します。

タスク失敗レスポンスの例：

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

サンプルコード

APIキーを取得します。クライアントアプリケーションに長期間有効なAPIキーをハードコードしないでください。アプリケーションサーバーで一時的なAPIキーを取得し、クライアントに送信することをお勧めします。
最新のSDKパッケージをダウンロードします。パッケージを抽出し、entry/libs/neonui.harをアプリケーションのentry/libsディレクトリにコピーし、entry/oh-package.json5に依存関係を追加します。

{
  "dependencies": {
    "neonui": "file:libs/neonui.har"
  }
}

DevEco StudioでSDKパッケージのサンプルプロジェクトを開きます。サンプルページはentry/src/main/ets/pages/dashscope/DashCosyVoiceStreamTtsPage.etsです。APIキーを設定してプロジェクトを実行します。

次のコードは、コアとなるストリーミング入力のフローを示しています。完全な音声再生、パラメーター選択、およびタスク状態管理については、SDK パッケージ内の DashCosyVoiceStreamTtsPage.ets を参照してください。

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const callback: INativeStreamInputTtsCallback = {
  onStreamInputTtsEventCallback: (event: StreamInputTtsEvent, taskId: string,
    sessionId: string, retCode: number, errorMsg: string,
    timestamp: string, allResponse: string): void => {
    if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE) {
      // Synthesis is complete.
    } else if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_TASK_FAILED) {
      // Handle the error based on retCode, errorMsg, or allResponse.
    }
  },
  onStreamInputTtsDataCallback: (data: ArrayBuffer | null): void => {
    if (data != null) {
      // Write PCM to AudioRenderer, or append encoded audio data in order.
    }
  }
};

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
const ticket: Record<string, Object> = {
  'url': 'wss://dashscope.aliyuncs.com/api-ws/v1/inference',
  'apikey': 'st-****',
  'device_id': 'my_device_id'
};
const parameters: Record<string, Object> = {
  'model': 'cosyvoice-v3-plus',
  'voice': 'longanyang',
  'format': 'mp3',
  'sample_rate': 24000,
  'enable_audio_decoder': true
};

const result = nuiInstance.startStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);

if (result == Constants.NuiResultCode.SUCCESS) {
  nuiInstance.sendStreamInputTts('Hello, ');
  nuiInstance.sendStreamInputTts('welcome to real-time speech synthesis.');
  nuiInstance.stopStreamInputTts(true);
}

// Call nuiInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

一括入力の場合は、直接 playStreamInputTts または asyncPlayStreamInputTts を呼び出します。

const oneShotInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
oneShotInstance.asyncPlayStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  'Hello, welcome to real-time speech synthesis.',
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);
// Call oneShotInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

高度な機能

SSML

目的：テキストにXMLタグを埋め込んで、発音、話速、ポーズ、その他の合成の詳細を制御します。

制限事項: SSML をサポートしているのは、一括入力 API の playStreamInputTts と asyncPlayStreamInputTts のみです。ストリーミング入力 API の sendStreamInputTts はサポートしていません。

使用方法: SDK は playStreamInputTts および asyncPlayStreamInputTts に対してデフォルトで SSML を有効にします。SSML テキストを text に渡してください。詳細については、SSML と LaTeXを参照してください。

数式

目的：モデルに一般的な数式や表現を正しく読み上げさせます。

使用方法: LaTeX 形式の数式を含むテキストを text に渡します。サポートされている構文については、LaTeX テキスト読み上げを参照してください。