Skip to main content

CosyVoice Android SDK

CosyVoice テキスト読み上げ（TTS）SDKを使用して、Androidアプリでテキストを表現力豊かで高品質な音声に変換します。

NativeNui

SDKは複数のNativeNuiインスタンスをサポートし、コールバックを使用して合成イベントを配信します。 アーキテクチャのハイライト:
  • 複数のインスタンス：new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS)を呼び出してインスタンスを作成します。
  • コールバック駆動：INativeStreamInputTtsCallbackインターフェースを通じてイベントと音声データを受信します。
  • イベントタイプ:
    • STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED：合成タスクが開始されました。
    • onStreamInputTtsDataCallback：音声データが配信されます。
    • STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE：合成タスクが完了しました。
    • STREAM_INPUT_TTS_EVENT_TASK_FAILED：合成タスクが失敗しました。

使用フロー

CosyVoiceは、一括入力とストリーミング入力の2つの呼び出しモードをサポートしています。 一括入力は、短いテキストやSSMLマークアップを使用するあらゆるシナリオに適しています。
  1. playStreamInputTts()またはasyncPlayStreamInputTts() — 完全なテキストを送信して合成を開始します。前者は同期であり、合成が完了した後に戻ります。後者は非同期であり、合成を開始した直後に戻ります。
  2. onStreamInputTtsDataCallback() — 音声データを受信します。
  3. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — 合成が完了しました。
ストリーミング入力は、リアルタイム会話や長文の「話しながら生成する」シナリオに適しています。このモードではSSMLはサポートされていません。
  1. startStreamInputTts() — SDKを初期化し、コールバックと接続パラメータを設定します。
  2. sendStreamInputTts() — テキストが利用可能になり次第、継続的に送信します。
  3. onStreamInputTtsDataCallback() — 音声データを受信します。
  4. stopStreamInputTts()またはasyncStopStreamInputTts() — 合成終了リクエストを送信します。前者は同期であり、合成が完了した後に戻ります。後者は非同期であり、リクエストを送信した直後に戻ります。
  5. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — 合成が完了しました。

startStreamInputTts

双方向ストリーミング合成を開始し、サービスへの接続を開き、イベントと音声データのコールバックを登録します。 このメソッドはブロックされる可能性があります。非 UI スレッドで呼び出してください。 メソッドシグネチャ: 
public synchronized int startStreamInputTts(INativeStreamInputTtsCallback callback,
                                            String ticket,
                                            String parameters,
                                            String session_id,
                                            int log_level,
                                            boolean save_log)
パラメーター:
パラメータ型説明
callbackINativeStreamInputTtsCallbackイベントおよびデータコールバックインターフェースの実装。
ticketString認証、接続、およびデバッグ設定を保持するJSON文字列。以下のticketパラメータリファレンスを参照してください。
parametersString音声合成の出力を制御するJSON文字列。以下のパラメータリファレンスを参照してください。
session_idStringクライアント指定のセッションID。省略した場合、サーバーが自動的に生成します。
log_levelintSDKの内部ログの詳細度を制御します。有効な値：
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (ログ記録を無効化)
save_logbooleanログをローカルファイルに書き込むかどうか。trueの場合、ticket内のdebug_pathを設定して保存先を指定し、オプションでmax_log_file_sizeを設定してファイルサイズの上限を指定します。
戻り値: エラーコード を返します。 チケットJSONの例: 
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id"
}
チケットパラメーター:
パラメータ型必須説明
urlStringはいサービスアドレス：
  • 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に置き換えます。
apikeyStringはいご自身のAPIキー。長期間有効なキーが漏洩した場合の影響範囲を制限するには、代わりに短期間有効な一時的なAPIキーを使用してください。
device_idStringはいエンドユーザーの一意の識別子。アプリ内のユーザーIDまたはクライアント生成のデバイス識別子に設定します。このIDは主にログの相関付けとトラブルシューティングに使用されます。
complete_waiting_msintいいえstopメソッドを呼び出した後、タイムアウトする前にSTREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEイベントを待機する時間（ミリ秒単位）。デフォルト：10000。
debug_pathStringいいえログファイルが書き込まれるローカルパス。このパラメータは、startStreamInputTts、playStreamInputTts、またはasyncPlayStreamInputTtsにおいてsave_logがtrueに設定されている場合にのみ有効です。その場合、パスは必須です。それ以外の場合、呼び出しはエラーを返します。デバイスには最大2つのログファイルが保持されます。
max_log_file_sizeintいいえログファイルの最大サイズ (バイト単位)。このパラメータは、startStreamInputTts、playStreamInputTts、またはasyncPlayStreamInputTtsにおいてsave_logがtrueに設定されている場合にのみ有効です。デフォルト: 104857600 (100 × 1024 × 1024バイト、または100 MiB)。
log_track_levelintいいえログコールバック（onStreamInputTtsLogTrackCallback）を通じて配信されるログのフィルターレベル。デフォルト：2。有効な値：
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (ログ記録を無効化)
注意：log_track_levelは、startStreamInputTts、playStreamInputTts、またはasyncPlayStreamInputTtsで設定されるlog_levelと連動して、どのログがコールバックに到達するかを決定します。ログエントリが配信されるには、log_track_levelとlog_levelの両方以上のレベルである必要があります。たとえば、log_track_levelが2（INFO）でlog_levelが3（WARNING）の場合、WARNING以上（レベル >= 3）のみがコールバックに到達します。
パラメーターJSONの例: 
{
    "model": "cosyvoice-v3-plus",
    "voice": "longanyang",
    "format": "mp3",
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
}
パラメーターリファレンス:
パラメータ型必須説明
modelStringはいモデル名。
voiceStringはい音声合成に使用される音声。
  • システム音声：CosyVoice音声リストを参照してください
  • クローン音声: 音声クローニングを通じて作成されたカスタム音声
  • カスタム音声: 音声デザインを通じて作成されたカスタム音声
formatStringいいえオーディオエンコーディング形式。有効な値：
  • pcm
  • wav
  • mp3 (デフォルト)
  • opus
enable_audio_decoderbooleanいいえSDKの内部デコーダーを有効にするかどうか。デフォルト: false。このパラメータは、音声エンコーディングフォーマットがopusまたはmp3の場合にのみ有効になります。有効にすると、SDKはopusまたはmp3の音声データをPCMデータにデコードしてから返します。
volumeintいいえ音量レベル。デフォルト値：50。有効な値：[0, 100]。
sample_rateintいいえオーディオサンプルレート (Hz)。有効な値: 8000、16000、22050 (デフォルト)、24000、44100、48000。
ratefloatいいえ話速。デフォルト値：1.0。有効な値：[0.5, 2.0]。
pitchfloatいいえピッチ。デフォルト値：1.0。有効な値：[0.5, 2.0]。
bit_rateintいいえkbps単位の音声ビットレート。音声フォーマットがmp3またはopusの場合、bit_rateを使用してビットレートを調整します。デフォルト値：32。有効な値：[6, 510]。
enable_ssmlbooleanいいえSSMLを有効にするかどうか。デフォルト：false。
  • true: 有効。
  • false: 無効。
SSMLの使用制限（サポートされているモデル、音声、API）については、制限事項を参照してください。
word_timestamp_enabledbooleanいいえ単語レベルのタイムスタンプを有効にするかどうかを指定します。デフォルト値：false。ストリーミング出力モードでのみ利用可能です。サポートされている音声：cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2のクローン音声、ならびにCosyVoice音声リストでサポート対象としてマークされているシステム音声。他のモデルのクローン音声では、この機能はサポートされていません。
単語のタイムスタンプは、INativeStreamInputTtsCallbackのall_responseフィールドで返されます。
seedintいいえ合成出力のバリエーションを制御するためのランダムシード。モデルバージョン、テキスト、音声、およびその他のパラメータが変更されていない場合、同じシードを使用すると同一の結果が生成されます。デフォルト値：0。有効な値：[0, 65535]。
language_hintsString[]いいえ
  • このパラメータは配列ですが、現在のバージョンでは最初の要素のみを処理します。単一の値を渡してください。
  • このパラメータは、音声合成のターゲット言語を指定します。音声クローンに使用される音声サンプルの言語とは無関係です。クローンタスクのソース言語を設定するには、音声クローンAPIリファレンスを参照してください。
出力品質を向上させるために音声合成のターゲット言語を指定します。数字の発音、略語の展開、記号の読み上げ、または少数民族言語の合成が期待通りでない場合は、このパラメータを使用します。例：
  • 予期しない数字の発音：「hello, this is 110」が、期待される中国語の発音ではなく「hello, this is one zero」と読み上げられる
  • 記号の発音が不正確：「@」が「at」ではなく中国語の相当する文字として読み上げられる
  • 少数言語の合成品質が低く、不自然な結果になる
  • zh: 中国語
  • en: 英語
  • fr: フランス語
  • de: ドイツ語
  • ja: 日本語
  • ko: 韓国語
  • ru: ロシア語
  • pt: ポルトガル語
  • th: タイ語
  • id: インドネシア語
  • vi: ベトナム語
  • es: スペイン語
  • it: イタリア語
  • ms: マレー語
  • fil: フィリピン語
  • ar: アラビア語
instructionStringいいえ方言、感情、話し方などの合成特性を制御します。使用法の詳細については、指示制御を参照してください。
enable_aigc_tagbooleanいいえ生成された音声にAIGCウォーターマークを埋め込むかどうかを指定します。trueに設定すると、サポートされているフォーマット（wav/mp3/opus）の音声ファイルにウォーターマークが埋め込まれます。デフォルト値：false。
cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2のみがこの機能をサポートしています。
aigc_propagatorStringいいえAIGCウォーターマークのContentPropagatorフィールドを設定し、コンテンツ伝播者を識別します。enable_aigc_tagがtrueの場合にのみ有効になります。デフォルト値: Alibaba Cloud UID。
cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2のみがこの機能をサポートしています。
aigc_propagate_idStringいいえAIGCウォーターマークのPropagateIDフィールドを設定し、特定の伝播アクションを一意に識別します。enable_aigc_tagがtrueの場合にのみ有効になります。デフォルト値: 現在の音声合成リクエストのリクエストID。
cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2のみがこの機能をサポートしています。
hot_fixobjectいいえ指定された単語の発音をカスタマイズしたり、合成前にテキストを置換したりするためのテキストホットフィックス設定。
cosyvoice-v2はこの機能をサポートしていません。
フィールド:
  • pronunciation: デフォルトの発音を修正する必要がある単語のピンイン注釈を指定します。
  • replace: 合成前に指定された単語を置換します。置換テキストが実際の合成入力として使用されます。
例:
"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}
enable_markdown_filterbooleanいいえ
この機能はcosyvoice-v3-flashのクローン音声のみでサポートされています。
合成前に入力テキストからMarkdownマークアップをフィルタリングして、マークアップが読み上げられないようにするかどうか。デフォルト：false。有効な値：
  • true: Markdownフィルタリングを有効にします。
  • false: Markdownフィルタリングを無効にします。

sendStreamInputTts

合成するテキストを送信します。このメソッドはstartStreamInputTtsと一緒に使用します。 startStreamInputTtsを呼び出した後、このメソッドを呼び出してテキストを継続的にプッシュします。 すべてのテキストを送信したら、stopStreamInputTtsまたはasyncStopStreamInputTtsを呼び出して入力を終了します。 メソッドシグネチャ: 
public synchronized int sendStreamInputTts(String text)
パラメーター:
パラメータ型説明
textString合成するテキスト。SSMLはサポートされていません。入力内のSSMLタグは解析されず、プレーンテキストとして読み上げられます。
戻り値: エラーコード を返します。

stopStreamInputTts

すべてのテキストが送信されたことをサーバーに通知し、すべての音声が合成されてSTREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEイベントが受信されるまでブロックする同期メソッド。 待機タイムアウトはcomplete_waiting_msによって制御されます。 メソッドシグネチャ: 
public synchronized int stopStreamInputTts()
戻り値: エラーコード を返します。

asyncStopStreamInputTts

すべてのテキストが送信されたことをサーバーに通知する非同期メソッド。呼び出しはすぐに戻り、合成はバックグラウンドで続行されます。 合成が完了したことを検出するには、STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEイベントを使用します。 メソッドシグネチャ: 
public synchronized int asyncStopStreamInputTts()
戻り値: エラーコード を返します。

cancelStreamInputTts

サーバーへの接続を即座に閉じ、現在の合成タスクを中止します。この呼び出しの後、それ以上の音声コールバックは配信されません。 メソッドシグネチャ: 
public synchronized int cancelStreamInputTts()
戻り値: エラーコード を返します。

playStreamInputTts

同期一括合成メソッド。呼び出しはテキストを送信し、音声の受信中はブロックされ、合成が完了した後にのみ戻ります。その後、stopメソッドを呼び出す必要はありません。 このメソッドではSSMLがデフォルトで有効になっています。オーバーライドするには、enable_ssmlを明示的に設定してください。 このメソッドは非UIスレッドで呼び出してください。 メソッドシグネチャ: 
public synchronized int playStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
パラメーター: callback、ticket、およびその他の共有パラメータは、startStreamInputTtsと同じ意味を持ちます。
パラメータ型説明
textString合成するテキスト。SSMLをサポートします。
戻り値: エラーコード を返します。

asyncPlayStreamInputTts

非同期一括合成メソッド。呼び出しはすぐに戻り、合成はバックグラウンドで実行され、結果はコールバックを通じて配信されます。その後、stopメソッドを呼び出す必要はありません。 このメソッドではSSMLがデフォルトで有効になっています。オーバーライドするには、enable_ssmlを明示的に設定してください。 メソッドシグネチャ: 
public synchronized int asyncPlayStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
パラメーター: callback、ticket、およびその他の共有パラメータは、startStreamInputTtsと同じ意味を持ちます。
パラメータ型説明
textString合成するテキスト。SSMLをサポートします。
戻り値: エラーコード を返します。

INativeStreamInputTtsCallback

CosyVoiceストリーミングTTSコールバックインターフェースは、合成イベント、音声データ、およびログを配信します。

onStreamInputTtsEventCallback: イベントの受信

メソッドシグネチャ: 
void onStreamInputTtsEventCallback(StreamInputTtsEvent event,
                                   String task_id,
                                   String session_id,
                                   int ret_code,
                                   String error_msg,
                                   String timestamp,
                                   String all_response);
パラメーター:
パラメータ型説明
eventStreamInputTtsEvent配信されるイベント。
task_idString合成タスクID。
session_idStringセッションID。クライアントから指定された場合はそのまま返されます。省略された場合はサーバーで生成されます。
ret_codeintエラーコード。STREAM_INPUT_TTS_EVENT_TASK_FAILEDイベントでのみ有効です。
error_msgStringエラーメッセージ。STREAM_INPUT_TTS_EVENT_TASK_FAILEDイベントでのみ有効です。
timestampString合成結果のタイムスタンプ情報。
all_responseString完全なJSONレスポンス。必要な追加データを抽出するために解析してください。

onStreamInputTtsDataCallback: オーディオデータの受信

SDKは合成中にこのコールバックを繰り返し呼び出します。コールバックから音声データを読み取ります。 メソッドシグネチャ: 
void onStreamInputTtsDataCallback(byte[] data);
パラメーター:
パラメータ型説明
databyte[]現在のセグメントのオーディオデータ。以下の用途に使用します:
  • 完全なオーディオファイルを組み立てて再生します。
  • ストリーミング対応プレーヤーでリアルタイムに再生します。
注意事項:
  • mp3やopusなどの圧縮フォーマットの場合、セグメント化された再生にはストリーミングプレーヤーが必要です。セグメントをフレームごとに再生すると、デコードが失敗する可能性があります。
  • 完全なファイルを組み立てるには、追記モードで開き、各セグメントを順番に書き込みます。
  • wavおよびmp3の場合、最初のonStreamInputTtsDataCallback呼び出しにのみファイルヘッダーが含まれます。後続の呼び出しには生の音声が格納されます。すべてのbufferチャンクを順番に連結してください。opusの場合、各フレームは自己完結型のOggページであり、直接連結できます。

onStreamInputTtsLogTrackCallback: トレースログの受信

このコールバックを使用してSDKから詳細な内部ログを受信します。これはトラブルシューティングとデバッグに役立ちます。 メソッドシグネチャ: 
default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent

CosyVoiceストリーミング音声合成のイベントタイプ列挙型。
イベント説明
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDサーバーがリクエストを受け付け、処理を開始しました。このイベントの直後に、onStreamInputTtsDataCallbackが最初の音声データを返し始めます。
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS課金データを含む、合成に関するランタイム情報。
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEサーバーがすべての音声データを送信し、onStreamInputTtsEventCallbackは再度呼び出されません。このイベントは、音声ストリームが終了したことを明示的に示すシグナルです。
STREAM_INPUT_TTS_EVENT_TASK_FAILEDタスクが失敗しました。原因を特定するには、INativeStreamInputTtsCallbackのall_responseフィールドでtask_id、error_code、およびerror_messageを確認してください。
{
    "header": {
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "event": "task-failed",
        "error_code": "InvalidParameter",
        "error_message": "[tts:]Engine return error code: 418",
        "attributes": {}
    },
    "payload": {}
}

サンプルコード

  1. APIキーの取得： APIキーの取得。セキュリティのため、APIキーは環境変数に保存してください。
    サードパーティアプリやユーザーに一時的なアクセスを許可する必要がある場合、または機密データへのアクセスや削除などの高リスク操作を厳密に制御したい（want）場合は、一時的なAPIキーを使用してください。一時的なAPIキーは60秒間有効であり、その後は新しいキーをリクエストする必要があります。
  2. SDKをダウンロードしてサンプルコードを実行します:
    • 最新のSDKパッケージをダウンロードします。
    • パッケージを解凍します。AARフォーマットのSDKはapp/libsにあります。これをプロジェクトの依存関係に追加してください。Android C++統合の場合、ZIP内のandroid_libsから共有ライブラリを、android_includeからヘッダーを取得します。
    • Android Studioでプロジェクトを開きます。サンプルコードはDashCosyVoiceStreamTtsActivity.javaにあります。APIキーをご自身のものに置き換えて、機能を試してください。

呼び出しモード

モード説明
一括テキスト入力手順:
  1. SDKおよびプレーヤーコンポーネントを初期化します。
  2. シナリオに合わせてパラメーターを設定します。
  3. playStreamInputTtsまたはasyncPlayStreamInputTtsを呼び出してテキストを送信し、合成を開始します。
  4. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEイベントを受信します — 合成が完了しました。
ユースケース:
  • 短文合成
  • SSMLマークアップが必要なシナリオ
ストリーミングテキスト入力手順:
  1. SDKおよびプレーヤーコンポーネントを初期化します。
  2. シナリオに合わせてパラメーターを設定します。
  3. startStreamInputTtsを呼び出してストリーミング合成を開始します。
  4. sendStreamInputTtsを呼び出して、テキストが利用可能になり次第、継続的に送信します。
  5. onStreamInputTtsDataCallbackでバイナリオーディオデータを受信します。
  6. stopStreamInputTtsまたはasyncStopStreamInputTtsを呼び出して入力を終了し、合成が完了するのを待ちます。
  7. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEイベントを受信します — 合成が完了しました。
ユースケース:
  • リアルタイム会話および長文の「随時読み上げる」シナリオ
  • このモードではSSMLマークアップはサポートされていません

高度な機能

SSMLマークアップ

目的：テキストにXMLタグを埋め込んで、発音、話す速度、ポーズ、その他の韻律の詳細を微調整します。 制限事項： SSMLは一括テキスト入力（playStreamInputTtsまたはasyncPlayStreamInputTtsメソッド）でのみサポートされています。ストリーミングテキスト入力（sendStreamInputTtsメソッド）ではSSMLはサポートされていません。 使用法：playStreamInputTtsまたはasyncPlayStreamInputTtsを呼び出すと、SDKはSSMLを自動的に有効にします。SSMLタグを含むテキストをtextパラメータを通じて渡してください。 詳細については、SSMLを参照してください。

数式

目的：モデルに一般的な数式や表現を正しく読み上げさせます。 使用法：LaTeX形式の数式を含むテキストをtextパラメータを通じて渡します。詳細については、LaTeX数式を音声に変換する（中国語のみ）を参照してください。