/**
* Runs a recognize request and returns the results immediately. Ideal when
* working with audio up to approximately one minute in length.
*
* The Google Cloud Client Library will attempt to infer the sample rate
* and encoding used by the provided audio file for you. This feature is
* recommended only if you are unsure of what the values may be and is
* currently limited to .flac, .amr, and .awb file types. The sample rate
* cannot be inferred from audio provided from a Google Storage object.
*
* Example:
* ```
* $results = $speech->recognize(
* fopen(__DIR__ . '/audio.flac', 'r')
* );
*
* foreach ($results as $result) {
* echo $result['transcript'];
* }
* ```
*
* ```
* // Run with speech context, sample rate, and encoding provided
* $results = $speech->recognize(
* fopen(__DIR__ . '/audio.flac', 'r'), [
* 'encoding' => 'FLAC',
* 'sampleRate' => 16000,
* 'speechContext' => [
* 'phrases' => [
* 'The Google Cloud Platform',
* 'Speech API'
* ]
* ]
* ]);
*
* foreach ($results as $result) {
* echo $result['transcript'];
* }
* ```
*
* @codingStandardsIgnoreStart
* @see https://cloud.google.com/speech/reference/rest/v1beta1/speech/syncrecognize#SpeechRecognitionAlternative SpeechRecognitionAlternative
* @see https://cloud.google.com/speech/reference/rest/v1beta1/speech/syncrecognize SyncRecognize API documentation
* @see https://cloud.google.com/speech/reference/rest/v1beta1/RecognitionConfig#AudioEncoding AudioEncoding types
* @see https://cloud.google.com/speech/docs/best-practices Speech API best practices
* @codingStandardsIgnoreEnd
*
* @param resource|string|StorageObject $audio The audio to recognize. May
* be a resource, string of bytes, or Google Cloud Storage object.
* @param array $options [optional] {
* Configuration options.
*
* @type int $sampleRate Sample rate in Hertz of the provided audio.
* 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). **Defaults to** `8000`
* with .amr files and `16000` with .awb files. If the
* getID3 library has been installed this value will **default
* to** the value read from the file's headers (if they exists).
* @type string $encoding Encoding of the provided audio. May be one of
* `"LINEAR16"`, `"FLAC"`, `"MULAW"`, `"AMR"`, `"AMR_WB"`. **Defaults to**
* `"FLAC"` with .flac files, `"AMR"` with .amr files and `"AMR_WB"`
* with .awb files.
* @type int $maxAlternatives Maximum number of alternatives to be
* returned. Valid values are 1-30. **Defaults to** `1`.
* @type string $languageCode The language of the content. BCP-47
* (e.g., `"en-US"`, `"es-ES"`) language codes are accepted. **Defaults to**
* `"en-US"` (English).
* @type bool $profanityFilter 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***\".
* **Defaults to** `false`.
* @type array $speechContext Must contain a key `phrases` which is to
* be an array of strings which provide "hints" to the speech
* recognizer to favor specific words and phrases in the results.
* Please see
* [SpeechContext](https://cloud.google.com/speech/reference/rest/v1beta1/RecognitionConfig#SpeechContext)
* for more information.
* }
* @return array The transcribed results. Each element of the array contains
* a `transcript` key which holds the transcribed text. Optionally
* a `confidence` key holding the confidence estimate ranging from
* 0.0 to 1.0 may be present. `confidence` is typically provided
* only for the top hypothesis.
* @throws \InvalidArgumentException
*/
public function recognize($audio, array $options = [])
{
$response = $this->connection->syncRecognize($this->formatRequest($audio, $options));
return isset($response['results']) ? $response['results'][0]['alternatives'] : [];
}