Alibaba Cloud Model Studio:Sambert音声合成HarmonyOS SDK

本ガイドでは、Sambert音声合成HarmonyOS SDKを使用してテキストを高品質で表現力豊かな音声に変換する方法について説明します。

ユーザーガイド： モデルの紹介および選択に関する推奨事項については、音声合成 - Sambertをご参照ください。

オンライン体験：サポートされていません。

{WorkspaceId} を実際のワークスペース ID に置き換えてください。既存のドメインも引き続き利用可能です。

NativeNui

このSDKはNativeNuiアーキテクチャに基づいており、コールバックを使用して音声合成イベントを処理します。

アーキテクチャの特徴：

• インスタンスモード：new NativeNui(Constants.ModeType.MODE_TTS)を使用して音声合成インスタンスを作成します。
• コールバック駆動：NuiTtsSdkListenerインターフェースを通じてイベントとデータを受信します。
• イベントタイプ：
  • NuiSdkTtsEvent：合成タスクが開始されました。
  • onTtsDataCallback：音声データが返されました。
  • NuiSdkTtsEvent：合成タスクが終了しました。
  • NuiSdkTtsEvent：合成エラーが発生しました。

手順

1. tts_initialize - SDKを初期化し、コールバックインターフェースと接続パラメータを設定します。
2. setParamTts - モデル、音声、音量などの音声合成効果パラメータを設定します。
3. startTts - 音声合成タスクを開始します。
4. onTtsDataCallback - 音声データを受信します。
5. tts_release - SDKリソースを解放します。

Sambertメソッド

tts_initialize

音声合成SDKインスタンスを初期化します。new NativeNui(Constants.ModeType.MODE_TTS)を使用してインスタンスを作成します。各インスタンスは1つの音声合成チャネルに対応します。tts_releaseを呼び出す前に、同じインスタンスを再度初期化しないでください。複数のタスクを並行して処理するには、複数のインスタンスを作成してください。

このインターフェースは呼び出し元のスレッドをブロックします。UIスレッド以外から呼び出してください。

メソッドシグネチャ：

public tts_initialize(callback: NuiTtsSdkListener,
                      ticket: string,
                      level: number,
                      save_log: boolean): number

パラメータの説明：

パラメーター	タイプ	説明
callback	NuiTtsSdkListener	イベントおよびデータコールバックインターフェースの実装。
ticket	string	認証、接続、およびデバッグのパラメータを含むJSON文字列。以下のticketパラメータの説明を参照してください。
level	number	SDKのログレベルを制御します。有効な値はConstants.LogLevel列挙型で定義されています。
save_log	boolean	ローカルログを保存するかどうかを指定します。このパラメータがtrueの場合、チケットパラメータのdebug_pathを使用してパスを指定してください。また、max_log_file_sizeを使用してファイルサイズを設定することもできます。

ticket JSON例：

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}

ticketパラメータの説明：

パラメーター	タイプ	必須	説明
url	string	はい	エンドポイント。これはwss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inferenceに固定されています。{WorkspaceId}を実際のワークスペースIDに置き換えてください。
apikey	string	はい	APIキー。長期的なキーの漏洩リスクを軽減するため、有効期間の短い、より安全な一時APIキーの使用を推奨します。
mode_type	string	はい	モードタイプです。オンライン音声合成モードを示す文字列 "2" に設定する必要があり、これは Constants.TtsModeTypeCloud に対応します。
device_id	string	はい	エンドユーザーを識別する一意の文字列。アプリ内のユーザーIDや、クライアントによって生成された一意のデバイス識別子に設定できます。このIDは主にログ追跡およびトラブルシューティングに使用されます。
debug_path	string	いいえ	ログファイルの保存パスです。このパラメータは、tts_initializeを呼び出す際にsave_logをtrueに設定した場合にのみ有効になります。この場合、ログファイルのパスを指定する必要があります。指定しない場合はエラーが発生します。ローカルには最大2つのログファイルが保持されます。
max_log_file_size	number	いいえ	ログファイルの最大サイズをバイト単位で設定します。このパラメータは、tts_initializeを呼び出す際にsave_logをtrueに設定した場合にのみ有効になります。デフォルト値：104857600（100 * 1024 * 1024バイト、つまり100 MiB）。

setParamTts

音声合成の効果パラメータをキーと値のペアとして設定します。このメソッドはstartTtsの前に呼び出してください。

メソッドシグネチャ：

public setParamTts(param: string, value: string): number

パラメータの説明：

パラメーター	タイプ	説明
param	string	パラメータ名。
value	string	パラメータ値。

利用可能なパラメータ：

パラメーター	タイプ	必須	説明
model	string	はい	モデル名（例：sambert-zhinan-v1）。
format	string	いいえ	音声エンコーディング形式。有効値：- pcm - wav - mp3（デフォルト）。
volume	string	いいえ	音量。デフォルト値：50。有効範囲：[0, 100]。
sample_rate	string	いいえ	オーディオサンプリングレート（Hz単位）です。有効な値は8000、16000、22050、24000、および48000です。ほとんどのSambert音声モデルのデフォルトサンプリングレートは48000です。対応するサンプリングレートを使用するようにプレーヤーを設定してください。
rate	string	いいえ	話速。デフォルト値：1.0。有効範囲：[0.5, 2.0]。
pitch	string	いいえ	ピッチ。デフォルト値：1.0。有効範囲：[0.5, 2.0]。
word_timestamp_enabled	string	いいえ	単語レベルのタイムスタンプを有効にするかどうかを指定します。デフォルト値：false。このパラメータはすべてのSambertモデルに適用されます。
phoneme_timestamp_enabled	string	いいえ	音素レベルのタイムスタンプを有効にするかどうかを指定します。デフォルト値：false。先にword_timestamp_enabledを有効にしてください。
enable_audio_decoder	string	いいえ	内蔵オーディオデコーダを有効にするかどうかを指定します。デフォルト値：0。有効な値：- 1：有効。formatがmp3の場合、このパラメータを"1"に設定してSDK内蔵デコーダを有効にします。その後、onTtsDataCallbackはデコードされたPCMデータを返します。- 0：無効。
enable_callback_vol	string	いいえ	ボリュームコールバックを有効にするかどうかを指定します。"1" に設定すると onTtsVolCallback が有効になります。
apikey	string	いいえ	実行時に一時的なAPIキーを更新します。合成タスクを開始する前に、setParamTts('apikey', ...)を使用して最新の一時的なキーを注入してください。

getparamTts

パラメータ値を取得します。このメソッドは主にトラブルシューティングに使用されます。

メソッドシグネチャ：

public getparamTts(param: string): string

パラメータの説明：

パラメーター	タイプ	説明
param	string	パラメータ名。現在、"error_msg"のみがサポートされています。

戻り値：

パラメータ値。

startTts

音声合成タスクを開始します。合成結果はコールバックを通じて返されます。

メソッドシグネチャ：

public startTts(priority: string, taskid: string, text: string): number

パラメータの説明：

パラメーター	タイプ	説明
priority	string	タスクの優先度。このパラメータは1に設定してください。
taskid	string	タスクID。空文字列''が渡された場合、SDKが自動的にIDを生成します。
text	string	合成するテキスト。

pauseTts

現在の音声合成タスクを一時停止します。タスクが一時停止された後、再開するにはresumeTtsを、キャンセルするにはcancelTtsを呼び出してください。タスクが一時停止されている間、SDKは新しい合成タスクを開始できません。

注意：この操作はサーバーからのデータ取得のみを一時停止します。プレーヤーにすでにバッファリングされている音声データは引き続き再生されます。

メソッドシグネチャ：

public pauseTts(): number

resumeTts

一時停止中の音声合成タスクを再開します。

メソッドシグネチャ：

public resumeTts(): number

cancelTts

合成タスクをキャンセルします。

注意：この操作はサーバーからのデータ取得のみをキャンセルします。プレーヤーにすでにバッファリングされている音声データは引き続き再生されます。

メソッドシグネチャ：

public cancelTts(taskid: string): number

パラメータの説明：

パラメーター	タイプ	説明
taskid	string	キャンセルするタスクのID。空文字列''が渡された場合、一時停止中または実行中のすべての合成タスクがキャンセルされます。

tts_release

すべての内部SDKリソースを解放し、アクティブなすべての合成タスクを強制終了します。このメソッドが呼び出された後、SDKインスタンスは使用できなくなります。再度使用するには、tts_initializeを呼び出して再初期化してください。

メソッドシグネチャ：

public tts_release(): number

NuiTtsSdkListener

Sambert音声合成コールバックインターフェースは、合成イベントとオーディオデータを受信します。HarmonyOS SDKでは、コールバックはArkTSアロー関数として定義されます。

onTtsEventCallback

音声合成タスクの開始、終了、キャンセル、一時停止、再開、およびエラーイベントをリッスンします。

メソッドシグネチャ：

onTtsEventCallback: (event: NuiSdkTtsEvent, taskid: string, ret_code: number) => void;

パラメータの説明：

パラメーター	タイプ	説明
event	NuiSdkTtsEvent	コールバックイベント。
taskid	string	音声合成タスクID。
ret_code	number	TTS_EVENT_ERROR イベントが発生した場合にのみ有効です。

onTtsDataCallback

合成中、SDKはこのコールバックを継続的にトリガーします。コールバックから音声データを取得してください。

メソッドシグネチャ：

onTtsDataCallback: (info: string, info_len: number, buffer: ArrayBuffer | null) => void;

パラメータの説明：

パラメーター	タイプ	説明
info	string	JSON形式のタイムスタンプ結果。このパラメータはword_timestamp_enabledが"1"に設定されている場合に有効になります。
info_len	number	infoフィールドのデータ長。このパラメータは無視できます。
buffer	ArrayBuffer | null	現在のセグメントの音声データ。このパラメータはnullになる場合があります。コールバック内でnullを確認してください。

onTtsVolCallback

enable_callback_volが有効化された後、このコールバックはSDKが直近に受信した合成データのボリュームを返します。これは現在再生中のボリュームではありません。

メソッドシグネチャ：

onTtsVolCallback: (vol: number) => void;

パラメータの説明：

パラメーター	タイプ	説明
vol	number	合成データの音量。

NuiSdkTtsEvent

Sambert音声合成イベントタイプの列挙型。

イベント	説明
TTS_EVENT_START	合成タスクが開始されました。音声データがまもなく返されます。
TTS_EVENT_END	合成タスクが正常に終了しました。すべての音声データがコールバックを通じて返されました。
TTS_EVENT_CANCEL	合成タスクがキャンセルされました。
TTS_EVENT_PAUSE	合成タスクが一時停止されました。
TTS_EVENT_RESUME	合成タスクが再開されました。
TTS_EVENT_ERROR	合成中にエラーが発生しました。詳細を取得するにはgetparamTts("error_msg")を呼び出してください。{ "header": { "task_id": "xxxxxxxxx", "event": "task-failed", "error_code": "InvalidParameter", "error_message": "Please ensure input text is valid.", "attributes": {} }, "payload": {} }

補助タイプ

Constants.LogLevel

levelパラメータの列挙値は以下の通りです：

値	説明
LOG_LEVEL_VERBOSE	最も詳細なログ。
LOG_LEVEL_DEBUG	デバッグログ。
LOG_LEVEL_INFO	情報ログ（デフォルト）。
LOG_LEVEL_WARNING	警告ログ。
LOG_LEVEL_ERROR	エラーログ。
LOG_LEVEL_NONE	ロギングを無効にします。

サンプルコード

1. API キーの取得： API キーの取得と設定。セキュリティのため、API キーを環境変数として設定することを推奨します。

   注記サードパーティのアプリケーションやユーザーに一時的なアクセス権を付与する場合、または機密データへのアクセスや削除などの高リスク操作を厳密に制御する場合は、一時的な API キーを使用してください。一時的な API キーの有効期間はデフォルトで 60 秒です。有効期限が切れた後は、新しいキーを取得してください。

2. SDK をダウンロードしてサンプルコードを実行します：

   • 最新のSDKパッケージをダウンロードしてください。
   • TARパッケージを展開します。neonuiディレクトリからHAR形式のSDKを取得し、プロジェクトの依存関係に追加してください。 C++統合の場合は、TARパッケージ内のnative/libsおよびnative/includeから動的ライブラリとヘッダーファイルを取得してください。
   • DevEco Studioでプロジェクトを開きます。サンプルコードはDashSambertTtsPage.etsにあります。APIキーを置き換えて機能を試してください。

呼び出し手順

1. SDKを初期化します：tts_initializeを呼び出し、NuiTtsSdkListenerコールバックとticketパラメータを渡します。
2. ビジネス要件に基づいてパラメータを設定します：setParamTtsを使用して、モデル、フォーマット、サンプリングレート、音声、ボリュームなどの音声合成効果パラメータを設定します。初期化成功直後に設定することを推奨します。
3. startTtsを呼び出して音声合成を開始します。
4. onTtsDataCallbackコールバックからオーディオデータを取得します。以下の「オーディオ再生」セクションで説明されているストリーミング再生を推奨します。オーディオをローカルに保存する場合は、合成が完了するまで同じファイルにオーディオデータを追加してください。
5. タスク終了後、tts_releaseを呼び出してSDKリソースを解放してください。

音声再生

HarmonyOSは@kit.AudioKitのAudioRendererを使用して合成音声を再生します。Sambert合成音声のデフォルトサンプリングレートは48 kHzであるため、プレーヤーのサンプリングレートを48000に設定してください。

製品サンプルでは、ロジックがAudioPlayer.etsユーティリティクラスにカプセル化されています。コンストラクタでサンプリングレートを指定してください：

// Play Sambert audio at the default sample rate of 48000. The default for AudioPlayer is 16000.
this.mAudioPlayer = new AudioPlayer(this, 48000);

プレーヤーはwriteDataコールバックを使用してキューからオーディオデータを取得し、AudioDataCallbackResult.VALIDまたはAudioDataCallbackResult.INVALIDを返します。onTtsEventCallbackがTTS_EVENT_ENDを受信すると、SDKは合成を完了し、すべてのデータをコールバックを通じて返しています。再生キューを完了としてマークすることで、プレーヤーは残りのデータの再生後に自動的に停止します。