// Copyright 2018 Google LLC. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. // syntax = "proto3"; package google.cloud.speech.v1; import "google/api/annotations.proto"; import "google/longrunning/operations.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; option cc_enable_arenas = true; option go_package = "google.golang.org/genproto/googleapis/cloud/speech/v1;speech"; option java_multiple_files = true; option java_outer_classname = "SpeechProto"; option java_package = "com.google.cloud.speech.v1"; // Service that implements Google Cloud Speech API. service Speech { // Performs synchronous speech recognition: receive results after all audio // has been sent and processed. rpc Recognize(RecognizeRequest) returns (RecognizeResponse) { option (google.api.http) = { post: "/v1/speech:recognize" body: "*" }; } // Performs asynchronous speech recognition: receive results via the // google.longrunning.Operations interface. Returns either an // `Operation.error` or an `Operation.response` which contains // a `LongRunningRecognizeResponse` message. rpc LongRunningRecognize(LongRunningRecognizeRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/speech:longrunningrecognize" body: "*" }; } // Performs bidirectional streaming speech recognition: receive results while // sending audio. This method is only available via the gRPC API (not REST). rpc StreamingRecognize(stream StreamingRecognizeRequest) returns (stream StreamingRecognizeResponse) {} } // The top-level message sent by the client for the `Recognize` method. message RecognizeRequest { // *Required* Provides information to the recognizer that specifies how to // process the request. RecognitionConfig config = 1; // *Required* The audio data to be recognized. RecognitionAudio audio = 2; } // The top-level message sent by the client for the `LongRunningRecognize` // method. message LongRunningRecognizeRequest { // *Required* Provides information to the recognizer that specifies how to // process the request. RecognitionConfig config = 1; // *Required* The audio data to be recognized. RecognitionAudio audio = 2; } // The top-level message sent by the client for the `StreamingRecognize` method. // Multiple `StreamingRecognizeRequest` messages are sent. The first message // must contain a `streaming_config` message and must not contain `audio` data. // All subsequent messages must contain `audio` data and must not contain a // `streaming_config` message. message StreamingRecognizeRequest { // The streaming request, which is either a streaming config or audio content. oneof streaming_request { // Provides information to the recognizer that specifies how to process the // request. The first `StreamingRecognizeRequest` message must contain a // `streaming_config` message. StreamingRecognitionConfig streaming_config = 1; // The audio data to be recognized. Sequential chunks of audio data are sent // in sequential `StreamingRecognizeRequest` messages. The first // `StreamingRecognizeRequest` message must not contain `audio_content` data // and all subsequent `StreamingRecognizeRequest` messages must contain // `audio_content` data. The audio bytes must be encoded as specified in // `RecognitionConfig`. Note: as with all bytes fields, protobuffers use a // pure binary representation (not base64). See // [content limits](/speech-to-text/quotas#content). bytes audio_content = 2; } } // Provides information to the recognizer that specifies how to process the // request. message StreamingRecognitionConfig { // *Required* Provides information to the recognizer that specifies how to // process the request. RecognitionConfig config = 1; // *Optional* If `false` or omitted, the recognizer will perform continuous // recognition (continuing to wait for and process audio even if the user // pauses speaking) until the client closes the input stream (gRPC API) or // until the maximum time limit has been reached. May return multiple // `StreamingRecognitionResult`s with the `is_final` flag set to `true`. // // If `true`, the recognizer will detect a single spoken utterance. When it // detects that the user has paused or stopped speaking, it will return an // `END_OF_SINGLE_UTTERANCE` event and cease recognition. It will return no // more than one `StreamingRecognitionResult` with the `is_final` flag set to // `true`. bool single_utterance = 2; // *Optional* If `true`, interim results (tentative hypotheses) may be // returned as they become available (these interim results are indicated with // the `is_final=false` flag). // If `false` or omitted, only `is_final=true` result(s) are returned. bool interim_results = 3; } // Provides information to the recognizer that specifies how to process the // request. message RecognitionConfig { // The encoding of the audio data sent in the request. // // All encodings support only 1 channel (mono) audio. // // For best results, the audio source should be captured and transmitted using // a lossless encoding (`FLAC` or `LINEAR16`). The accuracy of the speech // recognition can be reduced if lossy codecs are used to capture or transmit // audio, particularly if background noise is present. Lossy codecs include // `MULAW`, `AMR`, `AMR_WB`, `OGG_OPUS`, and `SPEEX_WITH_HEADER_BYTE`. // // The `FLAC` and `WAV` audio file formats include a header that describes the // included audio content. You can request recognition for `WAV` files that // contain either `LINEAR16` or `MULAW` encoded audio. // If you send `FLAC` or `WAV` audio file format in // your request, you do not need to specify an `AudioEncoding`; the audio // encoding format is determined from the file header. If you specify // an `AudioEncoding` when you send send `FLAC` or `WAV` audio, the // encoding configuration must match the encoding described in the audio // header; otherwise the request returns an // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] error // code. enum AudioEncoding { // Not specified. ENCODING_UNSPECIFIED = 0; // Uncompressed 16-bit signed little-endian samples (Linear PCM). LINEAR16 = 1; // `FLAC` (Free Lossless Audio // Codec) is the recommended encoding because it is // lossless--therefore recognition is not compromised--and // requires only about half the bandwidth of `LINEAR16`. `FLAC` stream // encoding supports 16-bit and 24-bit samples, however, not all fields in // `STREAMINFO` are supported. FLAC = 2; // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law. MULAW = 3; // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000. AMR = 4; // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000. AMR_WB = 5; // Opus encoded audio frames in Ogg container // ([OggOpus](https://wiki.xiph.org/OggOpus)). // `sample_rate_hertz` must be one of 8000, 12000, 16000, 24000, or 48000. OGG_OPUS = 6; // Although the use of lossy encodings is not recommended, if a very low // bitrate encoding is required, `OGG_OPUS` is highly preferred over // Speex encoding. The [Speex](https://speex.org/) encoding supported by // Cloud Speech API has a header byte in each block, as in MIME type // `audio/x-speex-with-header-byte`. // It is a variant of the RTP Speex encoding defined in // [RFC 5574](https://tools.ietf.org/html/rfc5574). // The stream is a sequence of blocks, one block per RTP packet. Each block // starts with a byte containing the length of the block, in bytes, followed // by one or more frames of Speex data, padded to an integral number of // bytes (octets) as specified in RFC 5574. In other words, each RTP header // is replaced with a single byte containing the block length. Only Speex // wideband is supported. `sample_rate_hertz` must be 16000. SPEEX_WITH_HEADER_BYTE = 7; } // Encoding of audio data sent in all `RecognitionAudio` messages. // This field is optional for `FLAC` and `WAV` audio files and required // for all other audio formats. For details, see // [AudioEncoding][google.cloud.speech.v1.RecognitionConfig.AudioEncoding]. AudioEncoding encoding = 1; // Sample rate in Hertz of the audio data sent in all // `RecognitionAudio` messages. Valid values are: 8000-48000. // 16000 is optimal. For best results, set the sampling rate of the audio // source to 16000 Hz. If that's not possible, use the native sample rate of // the audio source (instead of re-sampling). // This field is optional for `FLAC` and `WAV` audio files and required // for all other audio formats. For details, see // [AudioEncoding][google.cloud.speech.v1.RecognitionConfig.AudioEncoding]. int32 sample_rate_hertz = 2; // *Optional* The number of channels in the input audio data. // ONLY set this for MULTI-CHANNEL recognition. // Valid values for LINEAR16 and FLAC are `1`-`8`. // Valid values for OGG_OPUS are '1'-'254'. // Valid value for MULAW, AMR, AMR_WB and SPEEX_WITH_HEADER_BYTE is only `1`. // If `0` or omitted, defaults to one channel (mono). // Note: We only recognize the first channel by default. // To perform independent recognition on each channel set // `enable_separate_recognition_per_channel` to 'true'. int32 audio_channel_count = 7; // This needs to be set to `true` explicitly and `audio_channel_count` > 1 // to get each channel recognized separately. The recognition result will // contain a `channel_tag` field to state which channel that result belongs // to. If this is not true, we will only recognize the first channel. The // request is billed cumulatively for all channels recognized: // `audio_channel_count` multiplied by the length of the audio. bool enable_separate_recognition_per_channel = 12; // *Required* The language of the supplied audio as a // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag. // Example: "en-US". // See [Language Support](/speech-to-text/docs/languages) // for a list of the currently supported language codes. string language_code = 3; // *Optional* Maximum number of recognition hypotheses to be returned. // Specifically, the maximum number of `SpeechRecognitionAlternative` messages // within each `SpeechRecognitionResult`. // The server may return fewer than `max_alternatives`. // Valid values are `0`-`30`. A value of `0` or `1` will return a maximum of // one. If omitted, will return a maximum of one. int32 max_alternatives = 4; // *Optional* If set to `true`, the server will attempt to filter out // profanities, replacing all but the initial character in each filtered word // with asterisks, e.g. "f***". If set to `false` or omitted, profanities // won't be filtered out. bool profanity_filter = 5; // *Optional* array of [SpeechContext][google.cloud.speech.v1.SpeechContext]. // A means to provide context to assist the speech recognition. For more // information, see [Phrase Hints](/speech-to-text/docs/basics#phrase-hints). repeated SpeechContext speech_contexts = 6; // *Optional* If `true`, the top result includes a list of words and // the start and end time offsets (timestamps) for those words. If // `false`, no word-level time offset information is returned. The default is // `false`. bool enable_word_time_offsets = 8; // *Optional* If 'true', adds punctuation to recognition result hypotheses. // This feature is only available in select languages. Setting this for // requests in other languages has no effect at all. // The default 'false' value does not add punctuation to result hypotheses. // Note: This is currently offered as an experimental service, complimentary // to all users. In the future this may be exclusively available as a // premium feature. bool enable_automatic_punctuation = 11; // *Optional* Which model to select for the given request. Select the model // best suited to your domain to get best results. If a model is not // explicitly specified, then we auto-select a model based on the parameters // in the RecognitionConfig. //
Model | //Description | //
command_and_search |
// Best for short queries such as voice commands or voice search. | //
phone_call |
// Best for audio that originated from a phone call (typically // recorded at an 8khz sampling rate). | //
video |
// Best for audio that originated from from video or includes multiple // speakers. Ideally the audio is recorded at a 16khz or greater // sampling rate. This is a premium model that costs more than the // standard rate. | //
default |
// Best for audio that is not one of the specific audio models. // For example, long-form audio. Ideally the audio is high-fidelity, // recorded at a 16khz or greater sampling rate. | //