/**
* Runs a recognize request as an operation. Ideal when working with audio
* longer than approximately one minute. Requires polling of the returned
* operation in order to fetch results.
*
* 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.
*
* For longer audio, up to approximately 80 minutes, you must use Google
* Cloud Storage objects as input. In addition to this restriction, only
* LINEAR16 audio encoding can be used for long audio inputs.
*
* Example:
* ```
* $operation = $speech->beginRecognizeOperation(
* fopen(__DIR__ . '/audio.flac', 'r')
* );
*
* $isComplete = $operation->isComplete();
*
* while (!$isComplete) {
* sleep(1); // let's wait for a moment...
* $operation->reload();
* $isComplete = $operation->isComplete();
* }
*
* print_r($operation->results());
* ```
*
* ```
* // Run with speech context, sample rate, and encoding provided
* $operation = $speech->beginRecognizeOperation(
* fopen(__DIR__ . '/audio.flac', 'r'), [
* 'encoding' => 'FLAC',
* 'sampleRate' => 16000,
* 'speechContext' => [
* 'phrases' => [
* 'The Google Cloud Platform',
* 'Speech API'
* ]
* ]
* ]);
*
* $isComplete = $operation->isComplete();
*
* while (!$isComplete) {
* sleep(1); // let's wait for a moment...
* $operation->reload();
* $isComplete = $operation->isComplete();
* }
*
* print_r($operation->results());
* ```
*
* @codingStandardsIgnoreStart
* @see https://cloud.google.com/speech/reference/rest/v1beta1/operations Operations
* @see https://cloud.google.com/speech/reference/rest/v1beta1/speech/asyncrecognize AsyncRecognize 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 it 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"` (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 Operation
* @throws \InvalidArgumentException
*/
public function beginRecognizeOperation($audio, array $options = [])
{
$response = $this->connection->asyncRecognize($this->formatRequest($audio, $options));
return new Operation($this->connection, $response['name'], $response);
}