IBM Cloud Docs
WebSocket インターフェース

WebSocket インターフェース

IBM Watson® Speech to Text サービスの WebSocket インターフェースは、クライアントがサービスと対話するための最も自然な方法です。 音声認識のために WebSocket インターフェースを使用するには、最初に /v1/recognize メソッドを使用して、サービスとの持続的な接続を確立します。 その後、接続を介してテキスト・メッセージとバイナリー・メッセージを送信し、認識要求を開始して管理します。

WebSocket はその特長から、推奨される音声認識メカニズムです。 詳しくは、WebSocket インターフェースの利点を参照してください。 WebSocket インターフェースおよびそのパラメータの詳細については 、API & SDKリファレンスを参照してください。

WebSocket 接続の管理

WebSocket 認識要求および応答サイクルには、以下のステップがあります。

  1. 接続のオープン
  2. 認識要求の開始
  3. 音声の送信および認識結果の受信
  4. 認識要求の終了
  5. 追加要求の送信と要求パラメーターの変更
  6. 接続存続の維持
  7. 接続のクローズ

クライアントは、データをサービスに送信する際に、すべての JSON メッセージをテキスト・メッセージとして、またすべての音声データをバイナリー・メッセージとして渡す必要があります

以降のコード例のスニペットは、JavaScript で作成されており、HTML5 WebSocket API に基づいています。 WebSocket プロトコルに関する詳細は、インターネット技術タスクフォース(IETF) のRFC(Request for Comment)6455 を参照してください。

接続のオープン

Speech to Text サービスは WebSocket Secure (WSS) プロトコルを使用して、以下のエンドポイントで /v1/recognize メソッドを使用可能にします。

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

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

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

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

この資料の例では、wss://api.{location}.speech-to-text.watson.cloud.ibm.com/instances/{instance_id}{ws_url} に省略しています。 すべての WebSocket の例では、メソッドを {ws_url}/v1/recognize として呼び出します。

WebSocket クライアントは、以下の照会パラメーターを使用して /v1/recognize メソッドを呼び出し、サービスとの認証済み接続を確立します。 要求のこれらの側面は、WebSocket URL の照会パラメーターとしてのみ指定できます。

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 への認証」 を参照してください。
model (任意指定ストリング)

書き起こしで使用する言語モデルを指定します。 モデルを指定しない場合、サービスはデフォルトで en-US_BroadbandModel を使用します。 詳しくは、以下を参照してください

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

この接続を介して送信されるすべての要求で使用するカスタム言語モデルの GUID (Globally Unique Identifier) を指定します。 カスタム言語モデルの基本モデルは、model パラメーターの値と一致する必要があります。 カスタム言語モデル ID を含める場合は、カスタム・モデルを所有するサービスのインスタンスの資格情報を使用して要求を行う必要があります。 デフォルトでは、カスタム言語モデルは使用されません。 詳しくは、 音声認識にカスタム言語モデルの使用を参照してください。

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

接続を介して送信されるすべての要求に使用される、カスタム音響モデルの GUID を指定します。 カスタム音響モデルの基本モデルは、model パラメーターの値と一致する必要があります。 カスタム音響モデル ID を含める場合は、カスタム・モデルを所有するサービスのインスタンスの資格情報を使用して要求を行う必要があります。 デフォルトでは、カスタム音響モデルは使用されません。 詳しくは、音声認識にカスタム音響モデルの使用を参照してください。

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

この接続を介して送信されるすべての要求で使用する基本modelのバージョンを指定します。 このパラメーターは、主に新しい基本モデル用にアップグレードされたカスタム・モデルでの使用を目的としています。 デフォルト値は、このパラメーターをカスタム・モデルと共に使用するかどうかによって異なります。 詳しくは、アップグレードされたカスタム・モデルを使用した音声認識要求の実行を参照してください。

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

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

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

IBM Cloud 接続経由で送信されたリクエストと結果をサービスが記録するかどうかを示します。 一般的なサービス改善の目的で IBM がお客様のデータにアクセスすることを阻止するには、このパラメーターに対して true を指定します。 詳しくは、要求ロギングを参照してください。

以下の JavaScript コード・スニペットでは、サービスとの接続をオープンしています。 /v1/recognize メソッドの呼び出しで、access_token および model クエリー・パラメーターが渡されています。後者では、スペイン語の広帯域モデルを使用するようにサービスに指示しています。 接続の確立後に、クライアントはサービスからのイベントに対応するためのイベント・リスナー (onOpenonClose など) を定義します。 クライアントは複数の認識要求に接続を使用できます。

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token
  + '&model=es-ES_BroadbandModel';
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) };

クライアントはサービスへの複数の同時 WebSocket 接続をオープンできます。 同時接続の数は、サービスの容量によってのみ制限されます。通常これは、ユーザーにとって問題となりません。

認識要求の開始

認識要求を開始するために、クライアントは確立済みの接続を介してサービスに JSON テキスト・メッセージを送信します。 クライアントは、書き起こし対象の音声を送信する前に、このメッセージを送信する必要があります。 メッセージには action パラメーターを含める必要がありますが、通常は content-type パラメーターを省略できます。

action (必須ストリング)
実行するアクションを以下のように指定します。
content-type (任意指定ストリング)
要求の音声データのフォーマット (MIME タイプ) を識別します。 audio/alawaudio/basicaudio/l16、および audio/mulaw のフォーマットの場合、このパラメーターは必須です。 詳しくは、音声フォーマットを参照してください。

メッセージには、要求の処理方法に関する他の局面や、返す情報を指定するオプション・パラメーターを含めることもできます。 これらの追加パラメーターには、WebSocket インターフェースでのみ使用可能な interim_results パラメーターが含まれます。

  • すべての音声認識機能について詳しくは、パラメーターの要約を参照してください。
  • interim_results パラメーターについて詳しくは、中間結果を参照してください。

以下の JavaScript コード・スニペットでは、WebSocket 接続を介して認識要求の初期設定パラメーターを送信しています。 呼び出しは、クライアントの onOpen 関数に組み込まれて、接続の確立後にのみ送られるようになっています。

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/l16;rate=22050'
  };
  websocket.send(JSON.stringify(message));
}

要求を正常に受信すると、サービスは、以下のテキスト・メッセージを返して、listening であることを示します。 listening 状態は、サービス・インスタンスが構成されており (JSON start メッセージが有効であった)、認識要求の音声を受け入れる準備ができていることを示します。

{'state': 'listening'}

クライアントが認識要求に無効なクエリー・パラメーターまたは JSON フィールドを指定した場合、サービスの JSON 応答には、warnings フィールドが含まれます。 このフィールドはそれぞれの無効な引数について説明します。 警告に関係なく要求は成功します。

音声の送信および認識結果の受信

最初の start メッセージを送信した後、クライアントはサービスへの音声データの送信を開始できます。 クライアントは、サービスが start メッセージに listening メッセージで応答するのを待機する必要はありません。 サービスはリスニングを開始すると、listening メッセージの前に送信されたすべての音声を処理します。

クライアントは、音声をバイナリー・データとして送信する必要があります。 クライアントは、send 要求ごとに最大 100 MB の音声データを送信できます。 どんな要求に対しても少なくとも 100 バイトの音声を送信する必要があります。 クライアントは、単一の WebSocket 接続を介して複数の要求を送信できます。 圧縮を使用して、要求でサービスに渡すことができる音声の量を最大化する方法については、データ制限と圧縮を参照してください。

WebSocket インターフェースでは、最大 4 MB のフレーム・サイズ制限が課されます。 クライアントは、最大フレーム・サイズを 4 MB 未満に設定できます。 フレーム・サイズを設定することが実際的でない場合、クライアントは最大メッセージ・サイズを 4 MB 未満に設定し、音声データを一連のメッセージとして送信できます。 WebSocket フレームの詳細については 、IETF RFC 6455 を参照してください。

サービスが WebSocket 接続を介して認識結果を送信する方法は、クライアントが中間結果を要求するかどうかによって異なります。 詳しくは、サービスが認識結果を送信する方法を参照してください。

以下の JavaScript コード・スニペットでは、バイナリー・メッセージ (blob) として音声データをサービスに送信しています。

websocket.send(blob);

以下のスニペットでは、非同期的にサービスが返す認識の仮説を受け取っています。 この結果は、クライアントの onMessage 関数によって処理されます。

function onMessage(evt) {
  console.log(evt.data);
}

コードは、サービスからの戻りコードを処理できるように準備しておく必要があります。 詳しくは、WebSocket 戻りコードを参照してください。

認識要求の終了

サービスへの要求の音声データの送信が完了したら、クライアントは、以下の方法のいずれかで、バイナリー音声の送信の終了をサービスに通知する必要があります

  • action パラメーターを値 stop に設定した JSON テキスト・メッセージを送信する。

    {action: 'stop'}
    
  • blob が指定されていない、空のバイナリー・メッセージを送信する。

    websocket.send(blob)
    

クライアントが伝送完了のシグナル通知に失敗すると、サービスが最終結果を送信せずに接続がタイムアウトになる可能性があります。 複数の認識要求の間で最終結果を受信するには、クライアントは、後続の要求を送信する前に、直前の要求の送信の終了を通知する必要があります。 サービスは、最初の要求の最終結果を返した後に、別の {"state":"listening"} メッセージをクライアントに返します。 このメッセージは、サービスで別の要求を受信する準備ができていることを示します。

追加要求の送信と要求パラメーターの変更

WebSocket 接続がアクティブである間、クライアントはその接続を引き続き使用して、新しい音声の認識要求をさらに送信できます。 デフォルトでは、サービスは、同じ接続を介して送信される後続のすべての要求に対して、直前の start メッセージで送信されたパラメーターを引き続き使用します。

後続の要求のパラメーターを変更するために、クライアントは、最終認識結果と新しい {"state":"listening"} メッセージをサービスから受信した後、新しいパラメーターを使用して別の start メッセージを送信できます。 クライアントは、接続のオープン時に指定されたパラメーター (modellanguage_customization_id など) 以外の任意のパラメーターを変更できます。

次の例は、接続を介して送信される後続の認識要求に対する新しいパラメーターを指定して start メッセージを送信する例です。 このメッセージは、直前の例と同じ content-type を指定していますが、書き起こしの単語の信頼度とタイム・スタンプを返すようにサービスに指示しています。

var message = {
  action: 'start',
  content-type: 'audio/l16;rate=22050',
  word_confidence: true,
  timestamps: true
};
websocket.send(JSON.stringify(message));

接続存続の維持

サービスは、非アクティブ・タイムアウトまたはセッション・タイムアウトが発生すると、セッションを終了し、接続をクローズします。

  • 非アクティブ・タイムアウト が発生するのは、音声がクライアントから送信されているが、サービスで発話なし状態が検出された場合です。 非アクティブ・タイムアウトは、デフォルトで 30 秒に設定されています。 inactivity_timeout パラメーターを使用して、-1 (タイムアウトを無期限に設定する) などの別の値を指定できます。 詳しくは、非アクティブ・タイムアウトを参照してください。
  • セッション・タイムアウトが発生するのは、 30 秒間サービスがクライアントからデータを受信しなかった、または中間結果を送信しなかった場合です。 このタイムアウトの長さは変更できませんが、タイムアウトが発生する前に、単なる無音を含む任意の音声データをサービスに送信することでセッションを延長できます。 さらに inactivity_timeout-1 に設定する必要もあります。 セッションを延長するために送信した無音を含め、サービスにデータを送信した期間に対して課金されます。 詳しくは、セッション・タイムアウトを参照してください。

WebSocket クライアントとサーバーは、定期的に少量のデータを交換することでタイムアウトを防ぐために、ping-pong フレームを交換できます。 WebSocket スタックの多くは ping-pong フレームを交換しますが、この交換を行わないスタックもあります。 実装で ping-pong フレームが使用されるかどうかを判断するには、その実装のフィーチャーのリストを確認します。 ping-pong フレームをプログラムで判別または管理することはできません。

WebSocket スタックで ping-pong フレームが実装されていない場合に大きな音声ファイルを送信すると、接続で読み取りタイムアウトが発生することがあります。 このようなタイムアウトを回避するには、サービスに音声を継続的にストリーミングするか、またはサービスの中間結果を要求します。 いずれの方法でも、ping-pong フレームの欠落が原因で接続が閉じることがなくなります。

卓球台に関する詳細は、IETF RFC 6455 の セクション 5.5.2 Ping および セクション 5.5.3 Pong を参照してください。

接続のクローズ

クライアントは、サービスとの対話が完了した場合、WebSocket 接続をクローズすることができます。 接続がクローズされると、クライアントはその接続を使用して要求を送信したり結果を受信したりすることができなくなります。 クライアントが要求のすべての結果を受信した後でのみ、接続をクローズします。 クライアントが接続を明示的にクローズしない場合、接続は最終的にタイムアウトになり、クローズします。

以下の JavaScript コード・スニペットでは、オープン接続をクローズしています。

websocket.close();

サービスが認識結果を送信する方法

サービスが音声認識結果をクライアントに送信する方法は、クライアントが中間結果を要求するかどうかによって異なります。 要求に対する JSON 応答では、最終結果に "final": true というラベルが付けられ、中間結果に "final": false というラベルが付けられます。 詳しくは、中間結果を参照してください。

以下の例では、結果は、中間結果の有無にかかわらず送信された同じ入力音声に対するサービスの応答を示しています。 音声では、「one two ...休止... three four」という句が発話され、単語「two」と「three」の間に 1 秒間の休止があります。 休止は、個別の発話を表すのに十分な長さです。 発話は、通常は長時間の無音の結果として応答を引き出す入力音声のコンポーネントです。 詳しくは、音声認識の結果についてを参照してください。

結果に複数の最終結果が含まれている場合は、最終結果の transcript 要素を連結して、音声の完全な書き起こしにまとめます。 詳しくは、result_index フィールドを参照してください。

中間結果のない要求の例

クライアントは、interim_results パラメーターを false に設定するか、要求からパラメーターを省略することによって、中間結果を無効にします (パラメーターのデフォルト引数は falseです)。 クライアントは、stop メッセージを送信した後でのみ、応答として単一の JSON オブジェクトを受信します。

応答オブジェクトには、音声の個別の発話に対する複数の最終結果を含めることができます。 サービスは、要求の音声伝送が完了したことを示す stop メッセージを受信するまで、単一の応答オブジェクトを送信しません。 前世代モデルと次世代モデルのどちらを使用する場合でも、サービスの応答の構造とフォーマットは同じです。

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    },
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

中間結果を含む要求の例

クライアントは、以下のように中間結果を要求します。

  • 前世代モデルの場合、interim_results パラメーターを true に設定します。
  • 次世代モデルの場合、interim_results パラメーターと low_latency パラメーターの両方を true に設定します。 次世代モデルで中間結果を受け取るには、モデルが低遅延をサポートし、interim_results パラメーターと low_latency パラメーターの両方が true に設定されている必要があります。
    • 低遅延をサポートする次世代モデルについて詳しくは、サポートされる次世代モデルを参照してください。
    • 次世代モデルとの interim_results パラメーターおよび low_latency パラメーターの相互作用について詳しくは (パラメーターのさまざまな組み合わせを示す例を含める)、中間結果および低遅延の要求を参照してください。

クライアントは、応答として複数の JSON オブジェクトを受信します。 サービスは、中間結果ごと、および音声によって生成される最終結果ごとに、個別の応答オブジェクトを返します。 サービスは、最終結果ごとに少なくとも 1 つの中間結果を送信します。

サービスは、応答が使用可能になるとすぐに応答を送信します。 stop メッセージがその結果を送信するのを待ちませんが、stop メッセージは要求の伝送終了をシグナル通知する必要があります。 前世代モデルと次世代モデルのどちらを使用する場合でも、サービスの応答の構造とフォーマットは同じです。

{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "one two "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 0,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "one two "
        }
      ],
      "final": true
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "transcript": "three four "
        }
      ],
      "final": false
    }
  ]
}{
  "result_index": 1,
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.99,
          "transcript": "three four "
        }
      ],
      "final": true
    }
  ]
}

WebSocket 交換の例

以下の例は、単一の WebSocket 接続を介したクライアントと Speech to Text サービスの間の一連の交換を示しています。 これらの例は、メッセージとデータの交換に焦点を当てています。 接続のオープンとクローズは表示されません。 (これらの例は、前世代モデルに基づいているため、各応答の最終書き起こしには confidence フィールドが含まれています。)

最初のやり取りの例

最初のやり取りでは、クライアントは、ストリング「Name the Mayflower」が含まれている音声を送信しています。 クライアントは、PCM (audio/l16) 音声データの 1 つのチャンクを含んだバイナリー・メッセージを送信しています (そのために必要なサンプリング・レートを指定しています)。 クライアントは、サービスからの {"state":"listening"} 応答を待機せずに、音声データの送信を開始し、要求の終了を通知しています。 データを即時に送信することで、待ち時間が削減されます。これは、サービスで認識要求の処理の準備ができたときにすぐに音声を使用できるからです。

  • クライアントは以下を送信します。

    {
      "action": "start",
      "content-type": "audio/l16;rate=22050"
    }
    <binary audio data>
    {
      "action": "stop"
    }
    
  • サービスは以下のように応答します。

    {"state": "listening"}
    {"results": [{"alternatives": [{"transcript": "name the mayflower ",
                 "confidence": 0.91}], "final": true}], "result_index": 0}
    {"state":"listening"}
    

2 番目のやり取りの例

2 番目のやり取りでは、クライアントは、ストリング「Second audio transcript」が含まれている音声を送信しています。 クライアントは、単一のバイナリー・メッセージで音声を送信し、最初の要求で指定したのと同じパラメーターを使用しています。

  • クライアントは以下を送信します。

    <binary audio data>
    {
      "action": "stop"
    }
    
  • サービスは以下のように応答します。

    {"results": [{"alternatives": [{"transcript": "second audio transcript ",
                 "confidence": 0.99}], "final": true}], "result_index": 0}
    {"state":"listening"}
    

3 番目のやり取りの例

3 番目のやり取りでは、クライアントは、再度、ストリング「Name the Mayflower」が含まれている音声を送信しています。 PCM 音声データの単一のチャンクを含むバイナリー・メッセージを送信します。 しかし、今回は、クライアントはサービスからの中間結果を要求する新しい start メッセージを送信します。

  • クライアントは以下を送信します。

    {
      "action": "start",
      "content-type": "audio/l16;rate=22050",
      "interim_results": true
    }
    <binary audio data>
    {
      "action": "stop"
    }
    
  • サービスは以下のように応答します。

    {"results": [{"alternatives": [{"transcript": "name "}],
                 "final": false}], "result_index": 0}
    {"results": [{"alternatives": [{"transcript": "name may "}],
                 "final": false}], "result_index": 0}
    {"results": [{"alternatives": [{"transcript": "name may flour "}],
                 "final": false}], "result_index": 0}
    {"results": [{"alternatives": [{"transcript": "name the mayflower ",
                 "confidence": 0.91}], "final": true}], "result_index": 0}
    {"state":"listening"}
    

WebSocket 戻りコード

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

  • 1000。接続の正常なクローズを示し、接続が確立された目的が満たされたことを意味します。
  • 1002。プロトコル・エラーのため、サービスが接続をクローズすることを示します。
  • 1006。接続が異常にクローズされたことを示します。
  • 1009。フレーム・サイズが 4 MB の制限を超えたことを示します。
  • 1011。要求を満たすことができなくなる予期しない状態が発生したため、サービスが接続を終了することを示します。

ソケットがエラーでクローズされる場合、クライアントは、ソケットがクローズされる前に {"error":"{message}"} という形式の情報メッセージを受信します。 onerror イベント・ハンドラーを使用して、適切に応答します。 WebSocket リターンコードの詳細については 、IETF RFC 6455 を参照してください。

SDK の WebSocket 実装は、異なる応答コードまたは追加の応答コードを返すことがあります。 詳しくは、 API & SDK リファレンスを参照してください。