接続のオープン

WebSocket Secure (WSS) プロトコルで /v1/synthesize メソッドを呼び出して、サービスに対する接続を開きます。 このメソッドは、以下のエンドポイントで利用できます。

wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize

{location} は、アプリケーションがホストされている場所を示します。

• us-south (ダラス)
• us-east (ワシントン DC)
• eu-de (フランクフルト)
• au-syd (シドニー)
• jp-tok (東京)
• eu-gb (ロンドン)
• kr-seo (ソウル)

また、{instance_id} は、サービス・インスタンスの固有 ID です。

資料内の例では、wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} が {ws_url} に簡略化されています。 そのため、WebSocket のすべての例で、メソッドを {ws_url}/v1/synthesize として呼び出しています。

WebSocket クライアントは、以下の照会パラメーターを指定して/v1/synthesizeメソッドを呼び出し、サービスとの認証済み接続を確立します。

access_token (必須ストリング)

有効なアクセス・トークンを渡してサービスの認証を受けます。 期限が切れていない アクセス・トークンを使用する必要があります。

• IBM Cloud Identity and Access Management (IAM) アクセストークンを渡して、サービスで認証します。 呼び出しでは API キーではなく、IAM アクセス・トークンを渡します。 詳しくは、IBM Cloud に対する認証を参照してください。
• IBM Cloud Pak for DataIBM Software Hub HTTP リクエストの ヘッダーと同様に、アクセストークンを渡します。 Authorization 詳細は 、「 IBM Cloud Pak for Data への認証」 を参照してください。

voice (任意指定ストリング)

テキストを音声で発話する際の声を指定します。 サポートされる音声の現在のリストを取得するには、/v1/voices メソッドを使用します。 デフォルトの音声を使用するには、このパラメーターを省略します。 詳しくは、「言語とボイス」、「デフォルトのボイスを使う」をご覧ください。

customization_id (任意指定ストリング)

合成に使用するグローバル固有 ID (GUID) を指定します。 指定したカスタム・モデルは、合成用に使用する音声の言語と一致する必要があります。 カスタマイズ ID を含める場合は、カスタム・モデルを所有するサービス・インスタンスの資格情報を使用して要求を発行する必要があります。 カスタマイズなしで指定音声を使用する場合は、このパラメーターを省略します。 詳しくは、カスタマイズの理解を参照してください。

rate_percentage (任意 integer)

合成リクエスト全体のグローバルスピーキングレートを指定します。 話す速度は、サービスが音声合成したテキストを話す速度である。 レートを高くすると、テキストはより速く話され、レートを低くすると、テキストはよりゆっくりと話される。 このパラメータは、リクエスト全体の音声ごとのデフォルトレートを変更する。 詳しくは、スピーキングレートの変更 をご覧ください。

pitch_percentage (任意 integer)

合成リクエスト全体のグローバルなスピーキングピッチを指定します。 スピーキングピッチは、サービスが合成する音声のトーンを表す。 声のトーンの高さや低さが聞き手にどの程度感じられるかを表す。 ピッチが高ければ高いトーンで話し、低ければ低いトーンで話すことになる。 このパラメータは、リクエスト全体のボイスごとのデフォルトピッチを変更します。 詳しくは、ピッチの変更 をご覧ください。

spell_out_mode (任意指定ストリング)

*ドイツ語音声の場合、*文字列の個々の文字をどのように綴るかを指定する。 デフォルトでは、このサービスは、その言語のテキストを合成するのと同じ速度で個々の文字を綴ります。 このパラメータを使用すると、個々の文字を1つ singles 2つ pairs または3つ triples のグループに分けて、よりゆっくりと綴るようサービスに指示することができる。詳細については、文字列のスペルアウト方法を指定する を参照してください。

x-watson-metadata (任意指定ストリング)

接続を介して渡すデータに顧客 ID を関連 付けます。 このパラメーターは引数 customer_id={id} を受け入れます。ここで、id はデータに関連付けられるランダムまたは汎用の文字列です。 パラメーターの引数は URL エンコードにする必要があります。例: customer_id%3dmy_customer_ID。 デフォルトでは、データに顧客 ID は関連付けられません。 詳しくは、 機密保護を参照してください。

x-watson-learning-opt-out (任意指定 ブール)

IBM Cloud 接続経由で送信されたリクエストと結果をサービスが記録するかどうかを示します。 一般的なサービス改善の目的で IBM がお客様のデータにアクセスすることを阻止するには、このパラメーターに対して true を指定します。 オプトアウトすると、要求に応じて IBM がディスクにいいえユーザー・データ (テキストまたは音声) を書き込むように指示されます。 アカウントレベルでオプトアウトすることもできます。 詳しくは、要求ロギングを参照してください。

以下の JavaScript コード・スニペットでは、サービスとの接続をオープンしています。 /v1/synthesize メソッドの呼び出しで voice と access_token の照会パラメーターを渡しています。前者により、米国英語の Allison の音声を使用するようにサービスに命令しています。 接続が確立されると、サービスからのイベントに応答するようにイベント・リスナー (onOpen()、onClose()など) が定義されます。

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
  + '?access_token=' + access_token
  + '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

入力テキストを送信する

テキストを合成するために、クライアントは以下のパラメーターを使用して単純な JSON テキスト・メッセージをサービスに渡します。

text (必須ストリング)

合成するテキストを指定します。 クライアントは、 プレーン・テキストまたは SSML (Speech Synthesis Markup Language) のアノテーション付きのテキストを渡すことができます。 クライアントは、 要求で最大 5 KB の入力テキストを渡すことができます。 この制限には、指定するすべての SSML が 含まれます。 詳しくは、 入力テキストの指定 とその後のセクションを参照してください。 (SSML 入力には、<mark>要素を含めることもできます。 詳しくは、SSML マークの指定を参照してください。)

accept (必須ストリング)

要求する音声フォーマット (MIME タイプ) を指定します。 デフォルトの 音声フォーマット */* を要求するには、 audio/ogg;codecs=opus を使用します。 詳しくは、音声フォーマットの使用を参照してください。

Oggオーディオ・フォーマットはサファリ・ブラウザではサポートされていません。 SafariブラウザでText to Speechサービスを使用している場合は、音声を返す別のフォーマットを指定する必要があります。

timings (任意指定 ストリング[ ])

入力テキストのすべてのストリングの単語の タイミング情報をサービスから返すように指定します。 サービスは、入力の各トークンの 開始時間と終了時間を返します。 単語のタイミングを要求するには、 配列の唯一の要素として words を指定してください。 空の配列を指定したり、このパラメーターを省略したりすると、 単語のタイミングは受け取れません。 詳細については、ワードタイミングを生成する を参照してください。 日本語入力テキストではサポートされていません。

以下の JavaScript コード・スニペットでは、入力テキストとして「Hello world」というシンプルなメッセージを渡し、デフォルトの音声フォーマットを要求しています。 これらの呼び出しは、接続が確立された後にのみ送信されるようにするために、クライアント用に定義されたonOpen()関数に組み込まれます。

function onOpen(evt) {
  var message = {
    text: 'Hello world',
    accept: '*/*'
  };
  websocket.send(JSON.stringify(message));
}

サービスはこのメッセージへの応答として、音声応答のフォーマットを確認するテキスト・メッセージを送信します。 以下の応答は、デフォルトの音声フォーマットを確認しています。

{
  'binary_streams': [
    {
      content_type: 'audio/ogg;codecs=opus'
    }
  ]
}

応答の受信

音声フォーマットを確認すると、サービスは、指定されたフォーマットの合成音声をバイナリーのデータ・ストリームとして送信します。 ヘッダー (例えば、audio/wav や audio/ogg など) が組み込まれる音声フォーマットの場合、このサービスは、音声データを送信する前にヘッダーを返します。 ヘッダーは、複数のバイナリー応答をまたぐものになる場合があります。 すべての音声フォーマットで、クライアントは完全な音声応答を組み立てるために、サービスからのバイナリー応答をすべて追加する必要があります。

このサービスは、要求された音声フォーマットを確認するテキスト・メッセージを送信するだけでなく、警告またはエラーの発生時にテキスト・メッセージを送信することもできます。 また以下の場合に、このサービスはタイミング情報を含んだ 1 つ以上のテキスト・メッセージも送信します。

• 入力テキストに 1 つ以上の SSML<mark>要素が含まれています。
• 要求に timings パラメーターが指定されている場合。

クライアント側では、テキスト・メッセージへの応答、メッセージの表示、メッセージの取り込み (メッセージにマークの位置が含まれている場合などにアプリケーションで使用するため) のいずれかの処理を行うことができます。

入力テキストの合成と、すべてのバイナリー・メッセージとテキスト・メッセージの送信が完了すると、このサービスは自動的に WebSocket 接続を閉じます。 以下の単純なonMessage()関数は、サービスから受け取ったテキスト・メッセージとバイナリー・メッセージを、それらのタイプに基づいて適切な変数に追加します。 onClose() 関数が実行されるときには音声ストリーム全体が受信されていて、サービスはこれ以上バイナリー・メッセージやテキスト・メッセージを送信することはありません。

var messages;
var audioStream;

function onMessage(evt) {
  if (typeof evt.data === string) {
    messages += evt.data;
  } else {
    console.log('Received ' + evt.data.size() + ' binary bytes');
    audioStream += evt.data;
  }
}

function onClose(evt) {
  // The service's response is complete.
}

WebSocket 戻りコード

サービスは、WebSocket 接続を介して、以下の戻りコードをクライアントに送信できます。

• 1000。接続の正常なクローズを示し、接続が確立された目的が満たされたことを意味します。
• 1002。プロトコル・エラーのため、サービスが接続をクローズすることを示します。
• 1006。接続が異常にクローズされたことを示します。
• 1009。フレーム・サイズが 4 MB の制限を超えたことを示します。
• 1011。要求を満たすことができなくなる予期しない状態 (無効な引数など) が発生したため、サービスが接続を終了することを示します。 この戻りコードは、入力テキストが大きすぎたことを示している可能性もあります。

ソケットがエラーでクローズされる場合、サービスはクローズされる前に、{"error": "Specific error message"} という形式の情報メッセージをクライアントに送信します。 不明なパラメーターがある場合は、致命的ではない警告メッセージも送信します。 WebSocket 戻りコードの詳細については、インターネット技術タスクフォース（IETF）の RFC（Request for Comments）6455 をご覧ください。

SDK の WebSocket 実装は、異なる応答コードまたは追加の応答コードを返すことがあります。

{
  "warnings": "Unknown arguments: invalid-parameter."
}