cloud_speech.proto 39 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896
  1. // Copyright 2021 Google LLC
  2. //
  3. // Licensed under the Apache License, Version 2.0 (the "License");
  4. // you may not use this file except in compliance with the License.
  5. // You may obtain a copy of the License at
  6. //
  7. // http://www.apache.org/licenses/LICENSE-2.0
  8. //
  9. // Unless required by applicable law or agreed to in writing, software
  10. // distributed under the License is distributed on an "AS IS" BASIS,
  11. // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12. // See the License for the specific language governing permissions and
  13. // limitations under the License.
  14. syntax = "proto3";
  15. package google.cloud.speech.v1p1beta1;
  16. import "google/api/annotations.proto";
  17. import "google/api/client.proto";
  18. import "google/api/field_behavior.proto";
  19. import "google/cloud/speech/v1p1beta1/resource.proto";
  20. import "google/longrunning/operations.proto";
  21. import "google/protobuf/any.proto";
  22. import "google/protobuf/duration.proto";
  23. import "google/protobuf/timestamp.proto";
  24. import "google/protobuf/wrappers.proto";
  25. import "google/rpc/status.proto";
  26. option cc_enable_arenas = true;
  27. option go_package = "google.golang.org/genproto/googleapis/cloud/speech/v1p1beta1;speech";
  28. option java_multiple_files = true;
  29. option java_outer_classname = "SpeechProto";
  30. option java_package = "com.google.cloud.speech.v1p1beta1";
  31. option objc_class_prefix = "GCS";
  32. // Service that implements Google Cloud Speech API.
  33. service Speech {
  34. option (google.api.default_host) = "speech.googleapis.com";
  35. option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
  36. // Performs synchronous speech recognition: receive results after all audio
  37. // has been sent and processed.
  38. rpc Recognize(RecognizeRequest) returns (RecognizeResponse) {
  39. option (google.api.http) = {
  40. post: "/v1p1beta1/speech:recognize"
  41. body: "*"
  42. };
  43. option (google.api.method_signature) = "config,audio";
  44. }
  45. // Performs asynchronous speech recognition: receive results via the
  46. // google.longrunning.Operations interface. Returns either an
  47. // `Operation.error` or an `Operation.response` which contains
  48. // a `LongRunningRecognizeResponse` message.
  49. // For more information on asynchronous speech recognition, see the
  50. // [how-to](https://cloud.google.com/speech-to-text/docs/async-recognize).
  51. rpc LongRunningRecognize(LongRunningRecognizeRequest) returns (google.longrunning.Operation) {
  52. option (google.api.http) = {
  53. post: "/v1p1beta1/speech:longrunningrecognize"
  54. body: "*"
  55. };
  56. option (google.api.method_signature) = "config,audio";
  57. option (google.longrunning.operation_info) = {
  58. response_type: "LongRunningRecognizeResponse"
  59. metadata_type: "LongRunningRecognizeMetadata"
  60. };
  61. }
  62. // Performs bidirectional streaming speech recognition: receive results while
  63. // sending audio. This method is only available via the gRPC API (not REST).
  64. rpc StreamingRecognize(stream StreamingRecognizeRequest) returns (stream StreamingRecognizeResponse) {
  65. }
  66. }
  67. // The top-level message sent by the client for the `Recognize` method.
  68. message RecognizeRequest {
  69. // Required. Provides information to the recognizer that specifies how to
  70. // process the request.
  71. RecognitionConfig config = 1 [(google.api.field_behavior) = REQUIRED];
  72. // Required. The audio data to be recognized.
  73. RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];
  74. }
  75. // The top-level message sent by the client for the `LongRunningRecognize`
  76. // method.
  77. message LongRunningRecognizeRequest {
  78. // Required. Provides information to the recognizer that specifies how to
  79. // process the request.
  80. RecognitionConfig config = 1 [(google.api.field_behavior) = REQUIRED];
  81. // Required. The audio data to be recognized.
  82. RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];
  83. // Optional. Specifies an optional destination for the recognition results.
  84. TranscriptOutputConfig output_config = 4 [(google.api.field_behavior) = OPTIONAL];
  85. }
  86. // Specifies an optional destination for the recognition results.
  87. message TranscriptOutputConfig {
  88. oneof output_type {
  89. // Specifies a Cloud Storage URI for the recognition results. Must be
  90. // specified in the format: `gs://bucket_name/object_name`, and the bucket
  91. // must already exist.
  92. string gcs_uri = 1;
  93. }
  94. }
  95. // The top-level message sent by the client for the `StreamingRecognize` method.
  96. // Multiple `StreamingRecognizeRequest` messages are sent. The first message
  97. // must contain a `streaming_config` message and must not contain
  98. // `audio_content`. All subsequent messages must contain `audio_content` and
  99. // must not contain a `streaming_config` message.
  100. message StreamingRecognizeRequest {
  101. // The streaming request, which is either a streaming config or audio content.
  102. oneof streaming_request {
  103. // Provides information to the recognizer that specifies how to process the
  104. // request. The first `StreamingRecognizeRequest` message must contain a
  105. // `streaming_config` message.
  106. StreamingRecognitionConfig streaming_config = 1;
  107. // The audio data to be recognized. Sequential chunks of audio data are sent
  108. // in sequential `StreamingRecognizeRequest` messages. The first
  109. // `StreamingRecognizeRequest` message must not contain `audio_content` data
  110. // and all subsequent `StreamingRecognizeRequest` messages must contain
  111. // `audio_content` data. The audio bytes must be encoded as specified in
  112. // `RecognitionConfig`. Note: as with all bytes fields, proto buffers use a
  113. // pure binary representation (not base64). See
  114. // [content limits](https://cloud.google.com/speech-to-text/quotas#content).
  115. bytes audio_content = 2;
  116. }
  117. }
  118. // Provides information to the recognizer that specifies how to process the
  119. // request.
  120. message StreamingRecognitionConfig {
  121. // Required. Provides information to the recognizer that specifies how to
  122. // process the request.
  123. RecognitionConfig config = 1 [(google.api.field_behavior) = REQUIRED];
  124. // If `false` or omitted, the recognizer will perform continuous
  125. // recognition (continuing to wait for and process audio even if the user
  126. // pauses speaking) until the client closes the input stream (gRPC API) or
  127. // until the maximum time limit has been reached. May return multiple
  128. // `StreamingRecognitionResult`s with the `is_final` flag set to `true`.
  129. //
  130. // If `true`, the recognizer will detect a single spoken utterance. When it
  131. // detects that the user has paused or stopped speaking, it will return an
  132. // `END_OF_SINGLE_UTTERANCE` event and cease recognition. It will return no
  133. // more than one `StreamingRecognitionResult` with the `is_final` flag set to
  134. // `true`.
  135. //
  136. // The `single_utterance` field can only be used with specified models,
  137. // otherwise an error is thrown. The `model` field in [`RecognitionConfig`][]
  138. // must be set to:
  139. //
  140. // * `command_and_search`
  141. // * `phone_call` AND additional field `useEnhanced`=`true`
  142. // * The `model` field is left undefined. In this case the API auto-selects
  143. // a model based on any other parameters that you set in
  144. // `RecognitionConfig`.
  145. bool single_utterance = 2;
  146. // If `true`, interim results (tentative hypotheses) may be
  147. // returned as they become available (these interim results are indicated with
  148. // the `is_final=false` flag).
  149. // If `false` or omitted, only `is_final=true` result(s) are returned.
  150. bool interim_results = 3;
  151. }
  152. // Provides information to the recognizer that specifies how to process the
  153. // request.
  154. message RecognitionConfig {
  155. // The encoding of the audio data sent in the request.
  156. //
  157. // All encodings support only 1 channel (mono) audio, unless the
  158. // `audio_channel_count` and `enable_separate_recognition_per_channel` fields
  159. // are set.
  160. //
  161. // For best results, the audio source should be captured and transmitted using
  162. // a lossless encoding (`FLAC` or `LINEAR16`). The accuracy of the speech
  163. // recognition can be reduced if lossy codecs are used to capture or transmit
  164. // audio, particularly if background noise is present. Lossy codecs include
  165. // `MULAW`, `AMR`, `AMR_WB`, `OGG_OPUS`, `SPEEX_WITH_HEADER_BYTE`, `MP3`.
  166. //
  167. // The `FLAC` and `WAV` audio file formats include a header that describes the
  168. // included audio content. You can request recognition for `WAV` files that
  169. // contain either `LINEAR16` or `MULAW` encoded audio.
  170. // If you send `FLAC` or `WAV` audio file format in
  171. // your request, you do not need to specify an `AudioEncoding`; the audio
  172. // encoding format is determined from the file header. If you specify
  173. // an `AudioEncoding` when you send send `FLAC` or `WAV` audio, the
  174. // encoding configuration must match the encoding described in the audio
  175. // header; otherwise the request returns an
  176. // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT] error code.
  177. enum AudioEncoding {
  178. // Not specified.
  179. ENCODING_UNSPECIFIED = 0;
  180. // Uncompressed 16-bit signed little-endian samples (Linear PCM).
  181. LINEAR16 = 1;
  182. // `FLAC` (Free Lossless Audio
  183. // Codec) is the recommended encoding because it is
  184. // lossless--therefore recognition is not compromised--and
  185. // requires only about half the bandwidth of `LINEAR16`. `FLAC` stream
  186. // encoding supports 16-bit and 24-bit samples, however, not all fields in
  187. // `STREAMINFO` are supported.
  188. FLAC = 2;
  189. // 8-bit samples that compand 14-bit audio samples using G.711 PCMU/mu-law.
  190. MULAW = 3;
  191. // Adaptive Multi-Rate Narrowband codec. `sample_rate_hertz` must be 8000.
  192. AMR = 4;
  193. // Adaptive Multi-Rate Wideband codec. `sample_rate_hertz` must be 16000.
  194. AMR_WB = 5;
  195. // Opus encoded audio frames in Ogg container
  196. // ([OggOpus](https://wiki.xiph.org/OggOpus)).
  197. // `sample_rate_hertz` must be one of 8000, 12000, 16000, 24000, or 48000.
  198. OGG_OPUS = 6;
  199. // Although the use of lossy encodings is not recommended, if a very low
  200. // bitrate encoding is required, `OGG_OPUS` is highly preferred over
  201. // Speex encoding. The [Speex](https://speex.org/) encoding supported by
  202. // Cloud Speech API has a header byte in each block, as in MIME type
  203. // `audio/x-speex-with-header-byte`.
  204. // It is a variant of the RTP Speex encoding defined in
  205. // [RFC 5574](https://tools.ietf.org/html/rfc5574).
  206. // The stream is a sequence of blocks, one block per RTP packet. Each block
  207. // starts with a byte containing the length of the block, in bytes, followed
  208. // by one or more frames of Speex data, padded to an integral number of
  209. // bytes (octets) as specified in RFC 5574. In other words, each RTP header
  210. // is replaced with a single byte containing the block length. Only Speex
  211. // wideband is supported. `sample_rate_hertz` must be 16000.
  212. SPEEX_WITH_HEADER_BYTE = 7;
  213. // MP3 audio. MP3 encoding is a Beta feature and only available in
  214. // v1p1beta1. Support all standard MP3 bitrates (which range from 32-320
  215. // kbps). When using this encoding, `sample_rate_hertz` has to match the
  216. // sample rate of the file being used.
  217. MP3 = 8;
  218. // Opus encoded audio frames in WebM container
  219. // ([OggOpus](https://wiki.xiph.org/OggOpus)). This is a Beta features and
  220. // only available in v1p1beta1. `sample_rate_hertz` must be one of 8000,
  221. // 12000, 16000, 24000, or 48000.
  222. WEBM_OPUS = 9;
  223. }
  224. // Encoding of audio data sent in all `RecognitionAudio` messages.
  225. // This field is optional for `FLAC` and `WAV` audio files and required
  226. // for all other audio formats. For details, see [AudioEncoding][google.cloud.speech.v1p1beta1.RecognitionConfig.AudioEncoding].
  227. AudioEncoding encoding = 1;
  228. // Sample rate in Hertz of the audio data sent in all
  229. // `RecognitionAudio` messages. Valid values are: 8000-48000.
  230. // 16000 is optimal. For best results, set the sampling rate of the audio
  231. // source to 16000 Hz. If that's not possible, use the native sample rate of
  232. // the audio source (instead of re-sampling).
  233. // This field is optional for FLAC and WAV audio files, but is
  234. // required for all other audio formats. For details, see [AudioEncoding][google.cloud.speech.v1p1beta1.RecognitionConfig.AudioEncoding].
  235. int32 sample_rate_hertz = 2;
  236. // The number of channels in the input audio data.
  237. // ONLY set this for MULTI-CHANNEL recognition.
  238. // Valid values for LINEAR16 and FLAC are `1`-`8`.
  239. // Valid values for OGG_OPUS are '1'-'254'.
  240. // Valid value for MULAW, AMR, AMR_WB and SPEEX_WITH_HEADER_BYTE is only `1`.
  241. // If `0` or omitted, defaults to one channel (mono).
  242. // Note: We only recognize the first channel by default.
  243. // To perform independent recognition on each channel set
  244. // `enable_separate_recognition_per_channel` to 'true'.
  245. int32 audio_channel_count = 7;
  246. // This needs to be set to `true` explicitly and `audio_channel_count` > 1
  247. // to get each channel recognized separately. The recognition result will
  248. // contain a `channel_tag` field to state which channel that result belongs
  249. // to. If this is not true, we will only recognize the first channel. The
  250. // request is billed cumulatively for all channels recognized:
  251. // `audio_channel_count` multiplied by the length of the audio.
  252. bool enable_separate_recognition_per_channel = 12;
  253. // Required. The language of the supplied audio as a
  254. // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag.
  255. // Example: "en-US".
  256. // See [Language
  257. // Support](https://cloud.google.com/speech-to-text/docs/languages) for a list
  258. // of the currently supported language codes.
  259. string language_code = 3 [(google.api.field_behavior) = REQUIRED];
  260. // A list of up to 3 additional
  261. // [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tags,
  262. // listing possible alternative languages of the supplied audio.
  263. // See [Language
  264. // Support](https://cloud.google.com/speech-to-text/docs/languages) for a list
  265. // of the currently supported language codes. If alternative languages are
  266. // listed, recognition result will contain recognition in the most likely
  267. // language detected including the main language_code. The recognition result
  268. // will include the language tag of the language detected in the audio. Note:
  269. // This feature is only supported for Voice Command and Voice Search use cases
  270. // and performance may vary for other use cases (e.g., phone call
  271. // transcription).
  272. repeated string alternative_language_codes = 18;
  273. // Maximum number of recognition hypotheses to be returned.
  274. // Specifically, the maximum number of `SpeechRecognitionAlternative` messages
  275. // within each `SpeechRecognitionResult`.
  276. // The server may return fewer than `max_alternatives`.
  277. // Valid values are `0`-`30`. A value of `0` or `1` will return a maximum of
  278. // one. If omitted, will return a maximum of one.
  279. int32 max_alternatives = 4;
  280. // If set to `true`, the server will attempt to filter out
  281. // profanities, replacing all but the initial character in each filtered word
  282. // with asterisks, e.g. "f***". If set to `false` or omitted, profanities
  283. // won't be filtered out.
  284. bool profanity_filter = 5;
  285. // Speech adaptation configuration improves the accuracy of speech
  286. // recognition. When speech adaptation is set it supersedes the
  287. // `speech_contexts` field. For more information, see the [speech
  288. // adaptation](https://cloud.google.com/speech-to-text/docs/adaptation)
  289. // documentation.
  290. SpeechAdaptation adaptation = 20;
  291. // Array of [SpeechContext][google.cloud.speech.v1p1beta1.SpeechContext].
  292. // A means to provide context to assist the speech recognition. For more
  293. // information, see
  294. // [speech
  295. // adaptation](https://cloud.google.com/speech-to-text/docs/adaptation).
  296. repeated SpeechContext speech_contexts = 6;
  297. // If `true`, the top result includes a list of words and
  298. // the start and end time offsets (timestamps) for those words. If
  299. // `false`, no word-level time offset information is returned. The default is
  300. // `false`.
  301. bool enable_word_time_offsets = 8;
  302. // If `true`, the top result includes a list of words and the
  303. // confidence for those words. If `false`, no word-level confidence
  304. // information is returned. The default is `false`.
  305. bool enable_word_confidence = 15;
  306. // If 'true', adds punctuation to recognition result hypotheses.
  307. // This feature is only available in select languages. Setting this for
  308. // requests in other languages has no effect at all.
  309. // The default 'false' value does not add punctuation to result hypotheses.
  310. bool enable_automatic_punctuation = 11;
  311. // The spoken punctuation behavior for the call
  312. // If not set, uses default behavior based on model of choice
  313. // e.g. command_and_search will enable spoken punctuation by default
  314. // If 'true', replaces spoken punctuation with the corresponding symbols in
  315. // the request. For example, "how are you question mark" becomes "how are
  316. // you?". See https://cloud.google.com/speech-to-text/docs/spoken-punctuation
  317. // for support. If 'false', spoken punctuation is not replaced.
  318. google.protobuf.BoolValue enable_spoken_punctuation = 22;
  319. // The spoken emoji behavior for the call
  320. // If not set, uses default behavior based on model of choice
  321. // If 'true', adds spoken emoji formatting for the request. This will replace
  322. // spoken emojis with the corresponding Unicode symbols in the final
  323. // transcript. If 'false', spoken emojis are not replaced.
  324. google.protobuf.BoolValue enable_spoken_emojis = 23;
  325. // If 'true', enables speaker detection for each recognized word in
  326. // the top alternative of the recognition result using a speaker_tag provided
  327. // in the WordInfo.
  328. // Note: Use diarization_config instead.
  329. bool enable_speaker_diarization = 16 [deprecated = true];
  330. // If set, specifies the estimated number of speakers in the conversation.
  331. // Defaults to '2'. Ignored unless enable_speaker_diarization is set to true.
  332. // Note: Use diarization_config instead.
  333. int32 diarization_speaker_count = 17 [deprecated = true];
  334. // Config to enable speaker diarization and set additional
  335. // parameters to make diarization better suited for your application.
  336. // Note: When this is enabled, we send all the words from the beginning of the
  337. // audio for the top alternative in every consecutive STREAMING responses.
  338. // This is done in order to improve our speaker tags as our models learn to
  339. // identify the speakers in the conversation over time.
  340. // For non-streaming requests, the diarization results will be provided only
  341. // in the top alternative of the FINAL SpeechRecognitionResult.
  342. SpeakerDiarizationConfig diarization_config = 19;
  343. // Metadata regarding this request.
  344. RecognitionMetadata metadata = 9;
  345. // Which model to select for the given request. Select the model
  346. // best suited to your domain to get best results. If a model is not
  347. // explicitly specified, then we auto-select a model based on the parameters
  348. // in the RecognitionConfig.
  349. // <table>
  350. // <tr>
  351. // <td><b>Model</b></td>
  352. // <td><b>Description</b></td>
  353. // </tr>
  354. // <tr>
  355. // <td><code>command_and_search</code></td>
  356. // <td>Best for short queries such as voice commands or voice search.</td>
  357. // </tr>
  358. // <tr>
  359. // <td><code>phone_call</code></td>
  360. // <td>Best for audio that originated from a phone call (typically
  361. // recorded at an 8khz sampling rate).</td>
  362. // </tr>
  363. // <tr>
  364. // <td><code>video</code></td>
  365. // <td>Best for audio that originated from video or includes multiple
  366. // speakers. Ideally the audio is recorded at a 16khz or greater
  367. // sampling rate. This is a premium model that costs more than the
  368. // standard rate.</td>
  369. // </tr>
  370. // <tr>
  371. // <td><code>default</code></td>
  372. // <td>Best for audio that is not one of the specific audio models.
  373. // For example, long-form audio. Ideally the audio is high-fidelity,
  374. // recorded at a 16khz or greater sampling rate.</td>
  375. // </tr>
  376. // </table>
  377. string model = 13;
  378. // Set to true to use an enhanced model for speech recognition.
  379. // If `use_enhanced` is set to true and the `model` field is not set, then
  380. // an appropriate enhanced model is chosen if an enhanced model exists for
  381. // the audio.
  382. //
  383. // If `use_enhanced` is true and an enhanced version of the specified model
  384. // does not exist, then the speech is recognized using the standard version
  385. // of the specified model.
  386. bool use_enhanced = 14;
  387. }
  388. // Config to enable speaker diarization.
  389. message SpeakerDiarizationConfig {
  390. // If 'true', enables speaker detection for each recognized word in
  391. // the top alternative of the recognition result using a speaker_tag provided
  392. // in the WordInfo.
  393. bool enable_speaker_diarization = 1;
  394. // Minimum number of speakers in the conversation. This range gives you more
  395. // flexibility by allowing the system to automatically determine the correct
  396. // number of speakers. If not set, the default value is 2.
  397. int32 min_speaker_count = 2;
  398. // Maximum number of speakers in the conversation. This range gives you more
  399. // flexibility by allowing the system to automatically determine the correct
  400. // number of speakers. If not set, the default value is 6.
  401. int32 max_speaker_count = 3;
  402. // Output only. Unused.
  403. int32 speaker_tag = 5 [
  404. deprecated = true,
  405. (google.api.field_behavior) = OUTPUT_ONLY
  406. ];
  407. }
  408. // Description of audio data to be recognized.
  409. message RecognitionMetadata {
  410. // Use case categories that the audio recognition request can be described
  411. // by.
  412. enum InteractionType {
  413. // Use case is either unknown or is something other than one of the other
  414. // values below.
  415. INTERACTION_TYPE_UNSPECIFIED = 0;
  416. // Multiple people in a conversation or discussion. For example in a
  417. // meeting with two or more people actively participating. Typically
  418. // all the primary people speaking would be in the same room (if not,
  419. // see PHONE_CALL)
  420. DISCUSSION = 1;
  421. // One or more persons lecturing or presenting to others, mostly
  422. // uninterrupted.
  423. PRESENTATION = 2;
  424. // A phone-call or video-conference in which two or more people, who are
  425. // not in the same room, are actively participating.
  426. PHONE_CALL = 3;
  427. // A recorded message intended for another person to listen to.
  428. VOICEMAIL = 4;
  429. // Professionally produced audio (eg. TV Show, Podcast).
  430. PROFESSIONALLY_PRODUCED = 5;
  431. // Transcribe spoken questions and queries into text.
  432. VOICE_SEARCH = 6;
  433. // Transcribe voice commands, such as for controlling a device.
  434. VOICE_COMMAND = 7;
  435. // Transcribe speech to text to create a written document, such as a
  436. // text-message, email or report.
  437. DICTATION = 8;
  438. }
  439. // Enumerates the types of capture settings describing an audio file.
  440. enum MicrophoneDistance {
  441. // Audio type is not known.
  442. MICROPHONE_DISTANCE_UNSPECIFIED = 0;
  443. // The audio was captured from a closely placed microphone. Eg. phone,
  444. // dictaphone, or handheld microphone. Generally if there speaker is within
  445. // 1 meter of the microphone.
  446. NEARFIELD = 1;
  447. // The speaker if within 3 meters of the microphone.
  448. MIDFIELD = 2;
  449. // The speaker is more than 3 meters away from the microphone.
  450. FARFIELD = 3;
  451. }
  452. // The original media the speech was recorded on.
  453. enum OriginalMediaType {
  454. // Unknown original media type.
  455. ORIGINAL_MEDIA_TYPE_UNSPECIFIED = 0;
  456. // The speech data is an audio recording.
  457. AUDIO = 1;
  458. // The speech data originally recorded on a video.
  459. VIDEO = 2;
  460. }
  461. // The type of device the speech was recorded with.
  462. enum RecordingDeviceType {
  463. // The recording device is unknown.
  464. RECORDING_DEVICE_TYPE_UNSPECIFIED = 0;
  465. // Speech was recorded on a smartphone.
  466. SMARTPHONE = 1;
  467. // Speech was recorded using a personal computer or tablet.
  468. PC = 2;
  469. // Speech was recorded over a phone line.
  470. PHONE_LINE = 3;
  471. // Speech was recorded in a vehicle.
  472. VEHICLE = 4;
  473. // Speech was recorded outdoors.
  474. OTHER_OUTDOOR_DEVICE = 5;
  475. // Speech was recorded indoors.
  476. OTHER_INDOOR_DEVICE = 6;
  477. }
  478. // The use case most closely describing the audio content to be recognized.
  479. InteractionType interaction_type = 1;
  480. // The industry vertical to which this speech recognition request most
  481. // closely applies. This is most indicative of the topics contained
  482. // in the audio. Use the 6-digit NAICS code to identify the industry
  483. // vertical - see https://www.naics.com/search/.
  484. uint32 industry_naics_code_of_audio = 3;
  485. // The audio type that most closely describes the audio being recognized.
  486. MicrophoneDistance microphone_distance = 4;
  487. // The original media the speech was recorded on.
  488. OriginalMediaType original_media_type = 5;
  489. // The type of device the speech was recorded with.
  490. RecordingDeviceType recording_device_type = 6;
  491. // The device used to make the recording. Examples 'Nexus 5X' or
  492. // 'Polycom SoundStation IP 6000' or 'POTS' or 'VoIP' or
  493. // 'Cardioid Microphone'.
  494. string recording_device_name = 7;
  495. // Mime type of the original audio file. For example `audio/m4a`,
  496. // `audio/x-alaw-basic`, `audio/mp3`, `audio/3gpp`.
  497. // A list of possible audio mime types is maintained at
  498. // http://www.iana.org/assignments/media-types/media-types.xhtml#audio
  499. string original_mime_type = 8;
  500. // Obfuscated (privacy-protected) ID of the user, to identify number of
  501. // unique users using the service.
  502. int64 obfuscated_id = 9 [deprecated = true];
  503. // Description of the content. Eg. "Recordings of federal supreme court
  504. // hearings from 2012".
  505. string audio_topic = 10;
  506. }
  507. // Provides "hints" to the speech recognizer to favor specific words and phrases
  508. // in the results.
  509. message SpeechContext {
  510. // A list of strings containing words and phrases "hints" so that
  511. // the speech recognition is more likely to recognize them. This can be used
  512. // to improve the accuracy for specific words and phrases, for example, if
  513. // specific commands are typically spoken by the user. This can also be used
  514. // to add additional words to the vocabulary of the recognizer. See
  515. // [usage limits](https://cloud.google.com/speech-to-text/quotas#content).
  516. //
  517. // List items can also be set to classes for groups of words that represent
  518. // common concepts that occur in natural language. For example, rather than
  519. // providing phrase hints for every month of the year, using the $MONTH class
  520. // improves the likelihood of correctly transcribing audio that includes
  521. // months.
  522. repeated string phrases = 1;
  523. // Hint Boost. Positive value will increase the probability that a specific
  524. // phrase will be recognized over other similar sounding phrases. The higher
  525. // the boost, the higher the chance of false positive recognition as well.
  526. // Negative boost values would correspond to anti-biasing. Anti-biasing is not
  527. // enabled, so negative boost will simply be ignored. Though `boost` can
  528. // accept a wide range of positive values, most use cases are best served with
  529. // values between 0 and 20. We recommend using a binary search approach to
  530. // finding the optimal value for your use case.
  531. float boost = 4;
  532. }
  533. // Contains audio data in the encoding specified in the `RecognitionConfig`.
  534. // Either `content` or `uri` must be supplied. Supplying both or neither
  535. // returns [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]. See
  536. // [content limits](https://cloud.google.com/speech-to-text/quotas#content).
  537. message RecognitionAudio {
  538. // The audio source, which is either inline content or a Google Cloud
  539. // Storage uri.
  540. oneof audio_source {
  541. // The audio data bytes encoded as specified in
  542. // `RecognitionConfig`. Note: as with all bytes fields, proto buffers use a
  543. // pure binary representation, whereas JSON representations use base64.
  544. bytes content = 1;
  545. // URI that points to a file that contains audio data bytes as specified in
  546. // `RecognitionConfig`. The file must not be compressed (for example, gzip).
  547. // Currently, only Google Cloud Storage URIs are
  548. // supported, which must be specified in the following format:
  549. // `gs://bucket_name/object_name` (other URI formats return
  550. // [google.rpc.Code.INVALID_ARGUMENT][google.rpc.Code.INVALID_ARGUMENT]). For more information, see
  551. // [Request URIs](https://cloud.google.com/storage/docs/reference-uris).
  552. string uri = 2;
  553. }
  554. }
  555. // The only message returned to the client by the `Recognize` method. It
  556. // contains the result as zero or more sequential `SpeechRecognitionResult`
  557. // messages.
  558. message RecognizeResponse {
  559. // Sequential list of transcription results corresponding to
  560. // sequential portions of audio.
  561. repeated SpeechRecognitionResult results = 2;
  562. // When available, billed audio seconds for the corresponding request.
  563. google.protobuf.Duration total_billed_time = 3;
  564. }
  565. // The only message returned to the client by the `LongRunningRecognize` method.
  566. // It contains the result as zero or more sequential `SpeechRecognitionResult`
  567. // messages. It is included in the `result.response` field of the `Operation`
  568. // returned by the `GetOperation` call of the `google::longrunning::Operations`
  569. // service.
  570. message LongRunningRecognizeResponse {
  571. // Sequential list of transcription results corresponding to
  572. // sequential portions of audio.
  573. repeated SpeechRecognitionResult results = 2;
  574. // When available, billed audio seconds for the corresponding request.
  575. google.protobuf.Duration total_billed_time = 3;
  576. // Original output config if present in the request.
  577. TranscriptOutputConfig output_config = 6;
  578. // If the transcript output fails this field contains the relevant error.
  579. google.rpc.Status output_error = 7;
  580. }
  581. // Describes the progress of a long-running `LongRunningRecognize` call. It is
  582. // included in the `metadata` field of the `Operation` returned by the
  583. // `GetOperation` call of the `google::longrunning::Operations` service.
  584. message LongRunningRecognizeMetadata {
  585. // Approximate percentage of audio processed thus far. Guaranteed to be 100
  586. // when the audio is fully processed and the results are available.
  587. int32 progress_percent = 1;
  588. // Time when the request was received.
  589. google.protobuf.Timestamp start_time = 2;
  590. // Time of the most recent processing update.
  591. google.protobuf.Timestamp last_update_time = 3;
  592. // Output only. The URI of the audio file being transcribed. Empty if the audio was sent
  593. // as byte content.
  594. string uri = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  595. // Output only. A copy of the TranscriptOutputConfig if it was set in the request.
  596. TranscriptOutputConfig output_config = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  597. }
  598. // `StreamingRecognizeResponse` is the only message returned to the client by
  599. // `StreamingRecognize`. A series of zero or more `StreamingRecognizeResponse`
  600. // messages are streamed back to the client. If there is no recognizable
  601. // audio, and `single_utterance` is set to false, then no messages are streamed
  602. // back to the client.
  603. //
  604. // Here's an example of a series of `StreamingRecognizeResponse`s that might be
  605. // returned while processing audio:
  606. //
  607. // 1. results { alternatives { transcript: "tube" } stability: 0.01 }
  608. //
  609. // 2. results { alternatives { transcript: "to be a" } stability: 0.01 }
  610. //
  611. // 3. results { alternatives { transcript: "to be" } stability: 0.9 }
  612. // results { alternatives { transcript: " or not to be" } stability: 0.01 }
  613. //
  614. // 4. results { alternatives { transcript: "to be or not to be"
  615. // confidence: 0.92 }
  616. // alternatives { transcript: "to bee or not to bee" }
  617. // is_final: true }
  618. //
  619. // 5. results { alternatives { transcript: " that's" } stability: 0.01 }
  620. //
  621. // 6. results { alternatives { transcript: " that is" } stability: 0.9 }
  622. // results { alternatives { transcript: " the question" } stability: 0.01 }
  623. //
  624. // 7. results { alternatives { transcript: " that is the question"
  625. // confidence: 0.98 }
  626. // alternatives { transcript: " that was the question" }
  627. // is_final: true }
  628. //
  629. // Notes:
  630. //
  631. // - Only two of the above responses #4 and #7 contain final results; they are
  632. // indicated by `is_final: true`. Concatenating these together generates the
  633. // full transcript: "to be or not to be that is the question".
  634. //
  635. // - The others contain interim `results`. #3 and #6 contain two interim
  636. // `results`: the first portion has a high stability and is less likely to
  637. // change; the second portion has a low stability and is very likely to
  638. // change. A UI designer might choose to show only high stability `results`.
  639. //
  640. // - The specific `stability` and `confidence` values shown above are only for
  641. // illustrative purposes. Actual values may vary.
  642. //
  643. // - In each response, only one of these fields will be set:
  644. // `error`,
  645. // `speech_event_type`, or
  646. // one or more (repeated) `results`.
  647. message StreamingRecognizeResponse {
  648. // Indicates the type of speech event.
  649. enum SpeechEventType {
  650. // No speech event specified.
  651. SPEECH_EVENT_UNSPECIFIED = 0;
  652. // This event indicates that the server has detected the end of the user's
  653. // speech utterance and expects no additional speech. Therefore, the server
  654. // will not process additional audio (although it may subsequently return
  655. // additional results). The client should stop sending additional audio
  656. // data, half-close the gRPC connection, and wait for any additional results
  657. // until the server closes the gRPC connection. This event is only sent if
  658. // `single_utterance` was set to `true`, and is not used otherwise.
  659. END_OF_SINGLE_UTTERANCE = 1;
  660. }
  661. // If set, returns a [google.rpc.Status][google.rpc.Status] message that
  662. // specifies the error for the operation.
  663. google.rpc.Status error = 1;
  664. // This repeated list contains zero or more results that
  665. // correspond to consecutive portions of the audio currently being processed.
  666. // It contains zero or one `is_final=true` result (the newly settled portion),
  667. // followed by zero or more `is_final=false` results (the interim results).
  668. repeated StreamingRecognitionResult results = 2;
  669. // Indicates the type of speech event.
  670. SpeechEventType speech_event_type = 4;
  671. // When available, billed audio seconds for the stream.
  672. // Set only if this is the last response in the stream.
  673. google.protobuf.Duration total_billed_time = 5;
  674. }
  675. // A streaming speech recognition result corresponding to a portion of the audio
  676. // that is currently being processed.
  677. message StreamingRecognitionResult {
  678. // May contain one or more recognition hypotheses (up to the
  679. // maximum specified in `max_alternatives`).
  680. // These alternatives are ordered in terms of accuracy, with the top (first)
  681. // alternative being the most probable, as ranked by the recognizer.
  682. repeated SpeechRecognitionAlternative alternatives = 1;
  683. // If `false`, this `StreamingRecognitionResult` represents an
  684. // interim result that may change. If `true`, this is the final time the
  685. // speech service will return this particular `StreamingRecognitionResult`,
  686. // the recognizer will not return any further hypotheses for this portion of
  687. // the transcript and corresponding audio.
  688. bool is_final = 2;
  689. // An estimate of the likelihood that the recognizer will not
  690. // change its guess about this interim result. Values range from 0.0
  691. // (completely unstable) to 1.0 (completely stable).
  692. // This field is only provided for interim results (`is_final=false`).
  693. // The default of 0.0 is a sentinel value indicating `stability` was not set.
  694. float stability = 3;
  695. // Time offset of the end of this result relative to the
  696. // beginning of the audio.
  697. google.protobuf.Duration result_end_time = 4;
  698. // For multi-channel audio, this is the channel number corresponding to the
  699. // recognized result for the audio from that channel.
  700. // For audio_channel_count = N, its output values can range from '1' to 'N'.
  701. int32 channel_tag = 5;
  702. // Output only. The [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag
  703. // of the language in this result. This language code was detected to have
  704. // the most likelihood of being spoken in the audio.
  705. string language_code = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  706. }
  707. // A speech recognition result corresponding to a portion of the audio.
  708. message SpeechRecognitionResult {
  709. // May contain one or more recognition hypotheses (up to the
  710. // maximum specified in `max_alternatives`).
  711. // These alternatives are ordered in terms of accuracy, with the top (first)
  712. // alternative being the most probable, as ranked by the recognizer.
  713. repeated SpeechRecognitionAlternative alternatives = 1;
  714. // For multi-channel audio, this is the channel number corresponding to the
  715. // recognized result for the audio from that channel.
  716. // For audio_channel_count = N, its output values can range from '1' to 'N'.
  717. int32 channel_tag = 2;
  718. // Output only. The [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag
  719. // of the language in this result. This language code was detected to have
  720. // the most likelihood of being spoken in the audio.
  721. string language_code = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  722. }
  723. // Alternative hypotheses (a.k.a. n-best list).
  724. message SpeechRecognitionAlternative {
  725. // Transcript text representing the words that the user spoke.
  726. string transcript = 1;
  727. // The confidence estimate between 0.0 and 1.0. A higher number
  728. // indicates an estimated greater likelihood that the recognized words are
  729. // correct. This field is set only for the top alternative of a non-streaming
  730. // result or, of a streaming result where `is_final=true`.
  731. // This field is not guaranteed to be accurate and users should not rely on it
  732. // to be always provided.
  733. // The default of 0.0 is a sentinel value indicating `confidence` was not set.
  734. float confidence = 2;
  735. // A list of word-specific information for each recognized word.
  736. // Note: When `enable_speaker_diarization` is true, you will see all the words
  737. // from the beginning of the audio.
  738. repeated WordInfo words = 3;
  739. }
  740. // Word-specific information for recognized words.
  741. message WordInfo {
  742. // Time offset relative to the beginning of the audio,
  743. // and corresponding to the start of the spoken word.
  744. // This field is only set if `enable_word_time_offsets=true` and only
  745. // in the top hypothesis.
  746. // This is an experimental feature and the accuracy of the time offset can
  747. // vary.
  748. google.protobuf.Duration start_time = 1;
  749. // Time offset relative to the beginning of the audio,
  750. // and corresponding to the end of the spoken word.
  751. // This field is only set if `enable_word_time_offsets=true` and only
  752. // in the top hypothesis.
  753. // This is an experimental feature and the accuracy of the time offset can
  754. // vary.
  755. google.protobuf.Duration end_time = 2;
  756. // The word corresponding to this set of information.
  757. string word = 3;
  758. // The confidence estimate between 0.0 and 1.0. A higher number
  759. // indicates an estimated greater likelihood that the recognized words are
  760. // correct. This field is set only for the top alternative of a non-streaming
  761. // result or, of a streaming result where `is_final=true`.
  762. // This field is not guaranteed to be accurate and users should not rely on it
  763. // to be always provided.
  764. // The default of 0.0 is a sentinel value indicating `confidence` was not set.
  765. float confidence = 4;
  766. // Output only. A distinct integer value is assigned for every speaker within
  767. // the audio. This field specifies which one of those speakers was detected to
  768. // have spoken this word. Value ranges from '1' to diarization_speaker_count.
  769. // speaker_tag is set if enable_speaker_diarization = 'true' and only in the
  770. // top alternative.
  771. int32 speaker_tag = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  772. }