Speech-to-Text リクエストの構成

このドキュメントでは、Speech-to-Text の基本的な使い方を説明します。取り上げる内容は、Speech-to-Text に対するリクエストの種類、それらのリクエストの作成方法、リクエストに対するレスポンスの処理方法です。Speech-to-Text を使用するすべてのユーザーに、実際に API を使用する前にこのガイドと関連チュートリアルのいずれかを参照することをおすすめします。

使ってみる

Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Speech-to-Text のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Speech-to-Text の無料トライアル

Speech リクエスト

Speech-to-Text には 3 つの主要な音声認識方法があります。3 つの方法は次のとおりです。

同期認識（REST および gRPC）では、音声データを Speech-to-Text API に送信してデータの認識を行い、すべての音声が処理されたら結果を返します。同期認識リクエストは、時間が 1 分以内の音声データに制限されます。
非同期認識（REST および gRPC）では、音声データを Speech-to-Text API に送信し、長時間実行オペレーションを開始します。このオペレーションを使用することで、認識結果を定期的にポーリングできます。非同期認識リクエストは長さ 480 分までの音声データに使用します。
ストリーミング認識（gRPC のみ）では gRPC 双方向ストリームで提供された音声データの認識を行います。ストリーミングリクエストは、マイクからのライブ音声のキャプチャなどのリアルタイムの認識を目的として設計されています。ストリーミング認識では、音声をキャプチャしながら暫定的な結果を生成して、結果を表示できます。たとえば、ユーザーがまだ話している間に結果を表示できます。

リクエストには、音声データに加えて構成パラメータが含まれます。以下のセクションでは、これらの種類の認識リクエスト、それらが生成するレスポンス、それらのレスポンスの処理方法について詳しく説明します。

Speech-to-Text API 認識

Speech-to-Text API 同期認識リクエストは、スピーチ音声データに対して認識を行うための最も簡単な方法です。Speech-to-Text は、同期リクエストで送信された最大 1 分間のスピーチ音声データを処理できます。Speech-to-Text はすべての音声を処理して認識した後に、レスポンスを返します。

同期リクエストはブロッキングします。つまり、Speech-to-Text は次のリクエストを処理する前にレスポンスを返す必要があります。通常、Speech-to-Text はリアルタイムよりも速く音声を処理し、30 秒の音声を平均 15 秒で処理します。音声の品質が悪い場合は、認識リクエストの処理時間が大幅に長くなることがあります。

Speech-to-Text では、REST メソッドと gRPC メソッドの両方で Speech-to-Text API 同期リクエストと非同期リクエストを呼び出すことができます。この記事では、説明が簡単な REST API を使って、Speech-to-Text API の基本的な使用方法を説明します。ただし、REST リクエストも gRPC リクエストも基本構成は非常によく似ています。ストリーミング認識リクエストは、gRPC でのみサポートされています。

音声同期認識リクエスト

同期 Speech-to-Text API リクエストは音声認識構成と音声データで構成されます。サンプルリクエストを以下に示します。

{
    "config": {
        "encoding": "LINEAR16",
        "sampleRateHertz": 16000,
        "languageCode": "en-US",
    },
    "audio": {
        "uri": "gs://bucket-name/path_to_audio_file"
    }
}

Speech-to-Text API 同期認識リクエストのすべてに、音声認識の config フィールド（RecognitionConfig 型）を含める必要があります。RecognitionConfig には次のサブフィールドが含まれています。

encoding - （必須）提供された音声（AudioEncoding 型）のエンコードスキームを指定します。コーデックを選択できる場合は、良好なパフォーマンスを得るために、FLAC や LINEAR16 などのロスレスエンコードをおすすめします。詳細については、音声エンコードをご覧ください。encoding フィールドは FLAC ファイルと WAV ファイルでは省略可能です。これらのファイルでは、ファイルヘッダーにエンコードが含まれています。
sampleRateHertz - （必須）提供された音声のサンプルレートを指定します（ヘルツ単位）。サンプリングレートの詳細については、後述のサンプリングレートをご覧ください。sampleRateHertz フィールドは FLAC ファイルと WAV ファイルでは選択可能です。これらのファイルでは、ファイルヘッダーにサンプルレートが含まれています。
languageCode - （必須）提供された音声を認識する言語とリージョン / ロケールを指定します。言語コードは BCP-47 識別子である必要があります。言語コードは一般に第一言語タグと、言語が話される国を表す第二リージョンサブタグで構成されます（たとえば、前述の例の英語の「en」と米国の「US」など）。サポートされる言語については、サポートされる言語をご覧ください。
maxAlternatives - （省略可、デフォルト 1）レスポンスで表示する音声文字変換候補の数を示します。デフォルトでは、Speech-to-Text API は最も可能性が高い音声文字変換候補を 1 つ表示します。別の変換候補も表示するには、maxAlternatives を 1 よりも大きな値に設定します。Speech-to-Text は、品質が十分であると判断された変換候補のみ返します。変換候補の表示は一般に、ユーザーフィードバックを必要とするリアルタイムのリクエスト（音声コマンドなど）に適しているため、ストリーミング認識リクエスト向けです。
profanityFilter - （省略可）冒とく的な語句をフィルタで除外するかどうかを示します。フィルタで除外された単語は、先頭の文字と、残りの文字を表すアスタリスクで示されます（例: f***）。冒とくフィルタは単一の単語を検出するもので、不適切な表現がフレーズや単語の組み合わせである場合は検出しません。
speechContext - （省略可）この音声を処理するための追加のコンテキスト情報が含まれます。コンテキストには次のサブフィールドが含まれます。
- boost - 特定の単語やフレーズを認識するために重みを割り当てる値が含まれます。
- phrases - 音声認識タスクへのヒントを提供する語句のリストが含まれます。詳細については、音声適応の説明をご覧ください。

音声は、RecognitionAudio 型の audio パラメータを通して Speech-to-Text に渡されます。audio フィールドには、次のいずれかのサブフィールドが含まれます。

content には、リクエスト内に埋め込まれた評価対象の音声が格納されます。詳しくは、後述の音声コンテンツの埋め込みをご覧ください。このフィールド内で直接渡される音声は、時間が 1 分に制限されます。
uri には音声コンテンツを示す URI が含まれます。ファイルを（たとえば gzip などに）圧縮しないでください。現在、このフィールドには Google Cloud Storage URI を gs://bucket-name/path_to_audio_file という形式で指定する必要があります。後述の URI によって参照される音声を渡すをご覧ください。

これらのリクエストおよびレスポンスパラメータの詳細については、以下で説明します。

サンプルレート

音声のサンプリングレートはリクエスト構成の sampleRateHertz フィールドで指定し、関連する音声コンテンツまたはストリームのサンプリングレートと一致している必要があります。8,000 Hz から 48,000 Hz の間のサンプリングレートが、Speech-to-Text でサポートされています。sampleRateHertz フィールドを使用する代わりに、ファイルヘッダーで FLAC ファイルまたは WAV ファイルのサンプリングレートを指定できます。Speech-to-Text API に送信するには、FLAC ファイルで FLAC ヘッダーにサンプルレートを含める必要があります。

ソース素材のエンコード時に選択できる場合は、16,000 Hz のサンプルレートを使用して音声をキャプチャします。これより低い値では、音声認識の精度が低下する可能性があり、レベルを高くしても音声認識品質に目立った効果はありません。

ただし、音声データがすでに 16,000 Hz 以外の既存のサンプルレートで録音されている場合は、音声を 16,000 Hz で再サンプリングしないでください。たとえば、以前のほとんどの電話音声では 8,000 Hz のサンプルレートが使われており、正確な結果が生成されないことがあります。そのような音声を使用する必要がある場合は、ネィティブサンプルレートで音声を Speech API に渡します。

言語

Speech-to-Text の認識エンジンは、多様な言語をサポートしています。リクエスト構成の languageCode フィールドで、BCP-47 識別子を使用して音声の言語（および国または地域の方言）を指定します。

各機能でサポートされている言語の一覧については、言語サポートのページをご覧ください。

時間オフセット（タイムスタンプ）

Speech-to-Text では、提供された音声で認識された、発語された各単語の開始時点と終了時点を表す時間オフセット値（タイムスタンプ）を含めることができます。時間オフセット値は、音声の開始時点からの経過時間を 100 ミリ秒単位で表します。

時間オフセットは、長い音声ファイルを分析する際に特に役立ちます。長い音声ファイルでは、認識されたテキストで特定の単語を検索し、元の音声内でその単語の位置を指定（シーク）する必要がある場合があるためです。時間オフセットは、recognize、streamingrecognize、longrunningrecognize のすべての認識メソッドでサポートされています。

時間オフセット値は、認識レスポンスで返される最初の変換候補（alternative）にのみ含まれます。

リクエストの結果に時間オフセットを含めるには、リクエスト構成で enableWordTimeOffsets パラメータを true に設定します。REST API またはクライアントライブラリの使用例は、時間オフセット（タイムスタンプ）の使用をご覧ください。たとえば、次に示すように、リクエスト構成に enableWordTimeOffsets パラメータを含めることができます。

{
"config": {
  "languageCode": "en-US",
  "enableWordTimeOffsets": true
  },
"audio":{
  "uri":"gs://gcs-test-data/gettysburg.flac"
  }
}

Speech-to-Text API から返される結果には、次に示すように、認識された各単語の時間オフセット値が含まれます。

{
  "name": "6212202767953098955",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata",
    "progressPercent": 100,
    "startTime": "2017-07-24T10:21:22.013650Z",
    "lastUpdateTime": "2017-07-24T10:21:45.278630Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [
      {
        "alternatives": [
          {
            "transcript": "Four score and twenty...(etc)...",
            "confidence": 0.97186122,
            "words": [
              {
                "startTime": "1.300s",
                "endTime": "1.400s",
                "word": "Four"
              },
              {
                "startTime": "1.400s",
                "endTime": "1.600s",
                "word": "score"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.600s",
                "word": "and"
              },
              {
                "startTime": "1.600s",
                "endTime": "1.900s",
                "word": "twenty"
              },
              ...
            ]
          }
        ]
      },
      {
        "alternatives": [
          {
            "transcript": "for score and plenty...(etc)...",
            "confidence": 0.9041967,
          }
        ]
      }
    ]
  }
}

モデルの選択

Speech-to-Text は、機械学習モデルのいずれか 1 つを使用して、音声ファイルの文字変換を行います。Google では、特定の音声タイプとソースに対して音声認識モデルをトレーニングしています。

Speech-to-Text に音声文字変換リクエストを送信するときに、オリジナルの音声ソースを指定すると、変換結果を改善できます。これにより、Speech-to-Text API はそのタイプの音声用にトレーニングされた機械学習モデルを使用して音声ファイルを処理します。

音声認識のモデルを指定するには、リクエストの RecognitionConfig オブジェクトに model フィールドを追加し、使用するモデルを値として指定します。

利用可能な ML モデルについては、Speech-to-Text の音声文字変換モデルのリストをご覧ください。

埋め込み音声コンテンツ

リクエストの audio フィールドに content パラメータを渡すとき、音声認識リクエストに埋め込み音声が含まれます。gRPC リクエスト内のコンテンツとして渡される埋め込み音声の場合、その音声には Proto3 のシリアル化との互換性があり、バイナリデータとして渡す必要があります。REST リクエスト内のコンテンツとして渡される埋め込み音声の場合、その音声は JSON のシリアル化との互換性があり、最初に Base64 エンコードが行われている必要があります。詳細については、音声の Base64 エンコードをご覧ください。

Google Cloud クライアントライブラリを使用してリクエストを作成するときには、通常、このバイナリデータ（または Base64 でエンコードされたデータ）を content フィールドに直接書き出します。

URI で参照される音声を渡す

音声リクエストの audio フィールド内の uri パラメータに Google Cloud Storage 上の音声ファイル（base64 ではなく、バイナリ形式）を指定するのが一般的な方法です。この場合、次の形式にします。

gs://bucket-name/path_to_audio_file

たとえば、音声リクエストの次の部分は、クイックスタートで使用されるサンプル音声ファイルを参照しています。

...
    "audio": {
        "uri":"gs://cloud-samples-tests/speech/brooklyn.flac"
    }
...

Google Cloud Storage ファイルを読み取るには、次のいずれかの適切なアクセス許可が必要です。

一般公開されていて読み取り可能（サンプル音声ファイルなど）
サービスアカウントの承認を使用する場合、サービスアカウントによって読み取り可能
ユーザーアカウントの承認に 3-Legged OAuth を使用する場合、ユーザーアカウントによって読み取り可能

Google Cloud Storage へのアクセスの管理の詳細については、Google Cloud Storage ドキュメントのアクセス制御リストの作成と管理をご覧ください。

Speech-to-Text API レスポンス

これまでに説明したように、同期 Speech-to-Text API レスポンスは、渡される音声の長さに比例して、結果を返すまでに時間がかかることがあります。処理が終わると、API によって次に示すレスポンスが返されます。

{
  "results": [
    {
      "alternatives": [
        {
          "confidence": 0.98267895,
          "transcript": "how old is the Brooklyn Bridge"
        }
      ]
    }
  ]
}

各フィールドの内容は次のとおりです。

results には（SpeechRecognitionResult 型の）結果のリストが含まれます。このリストでは、各結果が音声のセグメントに対応します（音声のセグメントは一時停止で区切られます）。各結果は次の内から 1 つ以上のフィールドで構成されます。
- alternatives には SpeechRecognitionAlternatives 型の音声文字変換テキスト候補のリストが格納されます。複数の変換候補が表示されるかどうかは、ユーザーが（maxAlternatives に 1 より大きい値を設定して）複数の変換候補をリクエストしたかどうか、さらに Speech-to-Text が十分に高品質の変換候補を生成したかどうかによって異なります。各変換候補は次のフィールドから構成されます。
  - transcript には音声文字変換テキストが含まれます。後述の音声文字変換テキストの処理をご覧ください。
  - confidence には、Speech-to-Text の特定の音声文字変換の信頼度を示す 0 から 1 までの値が格納されます。後述の信頼値の解釈をご覧ください。

提供された音声から認識できる話し言葉がない場合、返される results リストには何も項目が含まれていません。話し言葉を認識できない場合、これは通常、音質が非常に低いか、言語コード、エンコード、またはサンプリングレートの値が提供された音声と一致しないことが原因です。

このレスポンスの構成要素については、以下のセクションで説明します。

同期 Speech-to-Text API の各レスポンスは、認識されたすべての音声が含まれる 1 つの結果ではなく、結果のリストを返します。transcript 要素内の認識された音声のリストは、連続して表示されます。

変換候補の選択

正常な同期認識レスポンス内の各結果には、1 つ以上の alternatives が含まれる場合があります（リクエストの maxAlternatives 値が 1 より大きい場合）。Speech-to-Text で、変換候補の信頼値が十分に高いと判断された場合、その変換候補はレスポンスに含まれます。レスポンスの最初の変換候補が、通常は最適な（最も可能性が高い）変換候補です。

maxAlternatives を 1 より大きい値に設定しても、複数の変換候補が返されるとは限りません。一般に、複数の変換候補は、ストリーミング認識リクエストによって結果を取得するユーザーにリアルタイムのオプションを提供する場合に適しています。

音声文字変換テキストの処理

レスポンスで指定された各変換候補には、認識されたテキストを格納する transcript が含まれます。このような音声文字変換テキストが連続した変換候補とともに提供される場合、それらを連結する必要があります。

次の Python コードは、結果リストに対して反復処理を行い、音声文字変換テキストを連結してまとめます。すべての場合に最初の変換候補（0 番目）を取得していることに注意してください。

response = service_request.execute()
recognized_text = 'Transcribed Text: \n'
for i in range(len(response['results'])):
    recognized_text += response['results'][i]['alternatives'][0]['transcript']

信頼値

confidence 値は 0.0 と 1.0 の間の推定値です。この値は、音声の各単語に割り当てられた「尤度」を集計して計算されます。数値が大きいほど、個々の単語が正しく認識された可能性が高くなります。通常、このフィールドは最上位の候補、かつ、is_final=true の結果のみに対して表示されます。たとえば、confidence 値を使用して、ユーザーに変換候補を示すか、ユーザーからの確認を求めるかどうかを決めることができます。

ただし、このモデルでは、「最」上位の結果を confidence のスコア（文の内容など）のみからではなく、より多くの信号に基づいて決めることに注意する必要があります。このため、上位の結果が最も高い信頼スコアを持たない場合があります。複数の代替候補を求めていない場合に、返された「最良の」結果の信頼値が予想より低くなることがあります。これは、あまり使われない単語が使用されている場合などに発生することがあります。あまり使われない単語が正しく認識された場合でも、低い「尤度」が割り当てられることがあります。モデルがコンテキストに基づき、その単語を最も可能性の高い単語であると判断した場合、結果の confidence 値が代替候補より低い場合でも最良の結果として返されます。

非同期リクエストとレスポンス

LongRunningRecognize メソッドへの非同期 Speech-to-Text API リクエストの形式は、同期 Speech-to-Text API リクエストと同じです。ただし、非同期リクエストは、レスポンスを返す代わりに長時間実行オペレーション（Operation 型）を開始し、このオペレーションを呼び出し元にすぐに返します。非同期音声認識では、最長 480 分までの音声を使用できます。

次に一般的なオペレーションレスポンスを示します。

{
  "name": "operation_name",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeMetadata"
    "progressPercent": 34,
    "startTime": "2016-08-30T23:26:29.579144Z",
    "lastUpdateTime": "2016-08-30T23:26:29.826903Z"
  }
}

結果がまだ存在していないことに注意してください。Speech-to-Text は引き続き音声を処理し、このオペレーションを使用して結果を保存します。LongRunningRecognize リクエストが完了すると、結果がオペレーションの response フィールドに表示されます。

次にリクエストの完了後のすべてのレスポンスを示します。

{
  "name": "1268386125834704889",
  "metadata": {
    "lastUpdateTime": "2016-08-31T00:16:32.169Z",
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongrunningRecognizeMetadata",
    "startTime": "2016-08-31T00:16:29.539820Z",
    "progressPercent": 100
  }
  "response": {
    "@type": "type.googleapis.com/google.cloud.speech.v1.LongRunningRecognizeResponse",
    "results": [{
      "alternatives": [{
        "confidence": 0.98267895,
        "transcript": "how old is the Brooklyn Bridge"
      }]}]
  },
  "done": True,
}

done が True に設定され、オペレーションの response に SpeechRecognitionResult 型の結果セットが格納されていることがわかります。この型は、同期 Speech-to-Text API 認識リクエストによって返される型と同じです。

デフォルトでは、非同期 REST レスポンスで done がデフォルト値の False に設定されます。ただし、JSON ではフィールドにデフォルト値が存在しなくても問題ないため、オペレーションが完了しているかどうかをテストする際に、done フィールドが存在していることと、True に設定されていることの両方をテストする必要があります。

ストリーミング Speech-to-Text API 認証リクエスト

ストリーミング Speech-to-Text API 認識呼び出しは、双方向ストリーム内の音声をリアルタイムでキャプチャし、認識するために設計されています。アプリケーションは、リクエストストリームで音声を送信し、レスポンスストリームで中間および最終認識結果をリアルタイムで受信できます。中間結果は音声の断片に対する現時点の認識結果を示しますが、最終認識結果は、その音声の断片の最終的で最良の予測を示します。

ストリーミングリクエスト

構成と音声の両方を 1 つのリクエストで送信する同期呼び出しや非同期呼び出しと異なり、ストリーミング Speech API の呼び出しでは複数のリクエストを送信する必要があります。最初の StreamingRecognizeRequest には、音声を伴わない StreamingRecognitionConfig 型の構成を含める必要があります。同じストリームで送信されるその後の StreamingRecognizeRequest は、生の音声バイトの連続フレームで構成されます。

StreamingRecognitionConfig は次のフィールドから構成されます。

config - （必須）RecognitionConfig 型の音声の構成情報が含まれます。これは同期リクエストや非同期リクエストで指定するものと同じです。
single_utterance - （省略可、デフォルト false）音声が検出されなくなったらこのリクエストを自動的に終了するかどうかを示します。設定されている場合、Speech-to-Text は一時停止、無音、スピーチ以外の音声を検出して、認識を終了するタイミングを判断します。設定しない場合、ストリームが直接クローズされるか、ストリームの上限長を超えるまで、ストリームは音声のリスニングと処理を続行します。single_utterance を true に設定すると、音声コマンドの処理に役立ちます。
interim_results - （省略可、デフォルト false）このストリームリクエストは、後で（さらに多くの音声の処理後に）絞り込むことができる一時結果を返す必要があることを示します。中間結果は、レスポンス内で is_final を false に設定することによって通知されます。

ストリーミングレスポンス

ストリーミング音声認識結果は、StreamingRecognitionResponse 型の一連のレスポンスで返されます。このようなレスポンスは次のフィールドから構成されます。

speechEventType には SpeechEventType 型のイベントが格納されます。このイベントの値は、1 つの発言が完了したと判断されたタイミングを示します。音声イベントは、ストリームのレスポンス内のマーカーとして機能します。
results には結果のリストが格納されます。これは、StreamingRecognitionResult 型の中間結果か最終結果のいずれかです。results リストには次のサブフィールドが含まれます。
- alternatives には候補の音声文字変換リストが含まれます。
- isFinal はこのリストエントリ内に取得された結果が中間結果か最終結果かを示します。単一のトリーム全体で複数の isFinal=true 結果が返されることがありますが、isFinal=true の結果は、書き込みストリームがクローズ（半クローズ）された後にのみ保証されます。
- stability はこれまで取得された結果の変動性、0.0 は完全な不安定性、1.0 は完全な安定性を示します。音声文字変換テキストが正しいかどうかを推定する信頼値とは異なり、stability は特定の部分結果が変更される可能性があるかどうかを推定します。isFinal が true に設定されている場合、stability は設定されません。