このドキュメントでは、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は設定されません。