Add Speech Streaming API.

Author: daspecster

docs/index.rst

@@ -176,6 +176,7 @@
   speech-encoding
   speech-metadata
   speech-operation
+  speech-streaming
   speech-sample
   speech-transcript
 

docs/speech-streaming.rst

@@ -0,0 +1,33 @@
+Speech StreamingResponseContainer
+=================================
+
+.. automodule:: google.cloud.speech.streaming.container
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Speech Streaming Request helpers
+================================
+
+.. automodule:: google.cloud.speech.streaming.request
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Speech StreamingSpeechResponse
+==============================
+
+.. automodule:: google.cloud.speech.streaming.response
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+
+
+Speech StreamingSpeechResult
+============================
+
+.. automodule:: google.cloud.speech.streaming.result
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/speech-usage.rst

@@ -145,5 +145,82 @@ words to the vocabulary of the recognizer.
     transcript: Hello, this is a test
     confidence: 0.81
 
+
+Streaming Recognition
+---------------------
+
+The :meth:`~google.cloud.speech.Client.stream_recognize` method converts speech
+data to possible text alternatives on the fly.
+
+.. note::
+    Streaming recognition requests are limited to 1 minute of audio.
+
+    See: https://cloud.google.com/speech/limits#content
+
+    >>> import io
+    >>> from google.cloud import speech
+    >>> from google.cloud.speech.encoding import Encoding
+    >>> client = speech.Client()
+    >>> with io.open('./hello.wav', 'rb') as stream:
+    >>>     sample = client.sample(stream=stream, encoding=Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    >>>     stream_container = client.stream_recognize(sample)
+    >>> print(stream_container)
+    <google.cloud.speech.streaming.container.StreamingResponseContainer object at 0x10538ee10>
+    >>> print(stream_container.responses)
+    {0: <google.cloud.speech.streaming.response.StreamingSpeechResponse object at 0x10f9ac9d0>}
+    >>> print(stream_container.responses[0].results[0].alternatives[0].confidence)
+    0.698092460632
+    >>> print(stream_container.is_finished)
+    True
+    >>> print stream_container.get_full_text()
+    hello
+
+By default the recognizer will perform continuous recognition
+(continuing to process audio even if the user pauses speaking) until the client
+closes the output stream or when the maximum time limit has been reached.
+
+If you only want to recognize a single utterance you can set
+ ``single_utterance`` to ``True`` and only one result will be returned.
+
+See: `Single Utterance`_
+
+.. code-block:: python
+
+    >>> with io.open('./hello_pause_goodbye.wav', 'rb') as stream:
+    >>>     sample = client.sample(stream=stream, encoding=Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    >>>     stream_container = client.stream_recognize(sample,
+    ...                                                single_utterance=True)
+    >>> print(stream_container.get_full_text())
+    hello
+
+
+If ``interim_results`` is set to ``True``, interim results
+(tentative hypotheses) may be returned as they become available.
+
+  .. code-block:: python
+
+    >>> with io.open('./hello_pause_goodbye.wav', 'rb') as stream:
+    >>>     sample = client.sample(stream=stream, encoding=Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    >>>     stream_container = client.stream_recognize(sample,
+    ...                                                interim_results=True)
+    >>> print(stream_container.get_full_text())
+    hello
+
+    >>> sample = client.sample(source_uri='gs://my-bucket/recording.flac',
+    ...                        encoding=Encoding.FLAC,
+    ...                        sample_rate=44100)
+    >>> results = client.stream_recognize(sample, interim_results=True)
+    >>> print(stream_container.responses[0].results[0].alternatives[0].transcript)
+    how
+    print(stream_container.responses[1].results[0].alternatives[0].transcript)
+    hello
+    >>> print(stream_container.responses[1].results[2].is_final)
+    True
+
+
+.. _Single Utterance: https://cloud.google.com/speech/reference/rpc/google.cloud.speech.v1beta1#streamingrecognitionconfig
 .. _sync_recognize: https://cloud.google.com/speech/reference/rest/v1beta1/speech/syncrecognize
 .. _Speech Asynchronous Recognize: https://cloud.google.com/speech/reference/rest/v1beta1/speech/asyncrecognize

scripts/verify_included_modules.py

@@ -45,6 +45,7 @@
     'google.cloud.pubsub.__init__',
     'google.cloud.resource_manager.__init__',
     'google.cloud.speech.__init__',
+    'google.cloud.speech.streaming.__init__',
     'google.cloud.storage.__init__',
     'google.cloud.streaming.__init__',
     'google.cloud.streaming.buffered_stream',

speech/google/cloud/speech/client.py

@@ -14,15 +14,30 @@
 
 """Basic client for Google Cloud Speech API."""
 
+import os
 from base64 import b64encode
 
 from google.cloud._helpers import _to_bytes
 from google.cloud._helpers import _bytes_to_unicode
 from google.cloud import client as client_module
+from google.cloud.environment_vars import DISABLE_GRPC
 from google.cloud.speech.connection import Connection
 from google.cloud.speech.encoding import Encoding
 from google.cloud.speech.operation import Operation
+from google.cloud.speech.streaming.request import _make_request_stream
 from google.cloud.speech.sample import Sample
+from google.cloud.speech.streaming.container import StreamingResponseContainer
+
+try:
+    from google.cloud.gapic.speech.v1beta1.speech_api import SpeechApi
+except ImportError:  # pragma: NO COVER
+    _HAVE_GAX = False
+else:
+    _HAVE_GAX = True
+
+
+_DISABLE_GAX = os.getenv(DISABLE_GRPC, False)
+_USE_GAX = _HAVE_GAX and not _DISABLE_GAX
 
 
 class Client(client_module.Client):
@@ -47,6 +62,7 @@ class Client(client_module.Client):
     """
 
     _connection_class = Connection
+    _speech_api = None
 
     def async_recognize(self, sample, language_code=None,
                         max_alternatives=None, profanity_filter=None,
@@ -104,7 +120,7 @@ def async_recognize(self, sample, language_code=None,
         return Operation.from_api_repr(self, api_response)
 
     @staticmethod
-    def sample(content=None, source_uri=None, encoding=None,
+    def sample(content=None, source_uri=None, stream=None, encoding=None,
                sample_rate=None):
         """Factory: construct Sample to use when making recognize requests.
 
@@ -118,6 +134,9 @@ def sample(content=None, source_uri=None, encoding=None,
                            supported, which must be specified in the following
                            format: ``gs://bucket_name/object_name``.
 
+        :type stream: :class:`io.BufferedReader`
+        :param stream: File like object to read audio data from.
+
         :type encoding: str
         :param encoding: encoding of audio data sent in all RecognitionAudio
                          messages, can be one of: :attr:`~.Encoding.LINEAR16`,
@@ -135,7 +154,7 @@ def sample(content=None, source_uri=None, encoding=None,
         :rtype: :class:`~google.cloud.speech.sample.Sample`
         :returns: Instance of ``Sample``.
         """
-        return Sample(content=content, source_uri=source_uri,
+        return Sample(content=content, source_uri=source_uri, stream=stream,
                       encoding=encoding, sample_rate=sample_rate)
 
     def sync_recognize(self, sample, language_code=None,
@@ -199,6 +218,108 @@ def sync_recognize(self, sample, language_code=None,
         else:
             raise ValueError('result in api should have length 1')
 
+    def stream_recognize(self, sample, language_code=None,
+                         max_alternatives=None, profanity_filter=None,
+                         speech_context=None, single_utterance=False,
+                         interim_results=False):
+        """Streaming speech recognition.
+
+        .. note::
+            Streaming recognition requests are limited to 1 minute of audio.
+
+            See: https://cloud.google.com/speech/limits#content
+
+        :type sample: :class:`~google.cloud.speech.sample.Sample`
+        :param sample: Instance of ``Sample`` containing audio information.
+
+        :type language_code: str
+        :param language_code: (Optional) The language of the supplied audio as
+                              BCP-47 language tag. Example: ``'en-GB'``.
+                              If omitted, defaults to ``'en-US'``.
+
+        :type max_alternatives: int
+        :param max_alternatives: (Optional) Maximum number of recognition
+                                 hypotheses to be returned. The server may
+                                 return fewer than maxAlternatives.
+                                 Valid values are 0-30. A value of 0 or 1
+                                 will return a maximum of 1. Defaults to 1
+
+        :type profanity_filter: bool
+        :param profanity_filter: If 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 False or
+                                 omitted, profanities won't be filtered out.
+
+        :type speech_context: list
+        :param speech_context: A list of strings (max 50) containing words and
+                               phrases "hints" so that the speech recognition
+                               is more likely to recognize them. This can be
+                               used to improve the accuracy for specific words
+                               and phrases. This can also be used to add new
+                               words to the vocabulary of the recognizer.
+
+        :type single_utterance: boolean
+        :param single_utterance: [Optional] If false or omitted, the recognizer
+                                 will perform continuous recognition
+                                 (continuing to process audio even if the user
+                                 pauses speaking) until the client closes the
+                                 output stream (gRPC API) or when the maximum
+                                 time limit has been reached. Multiple
+                                 SpeechRecognitionResults with the is_final
+                                 flag set to true may be returned.
+
+                                 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_UTTERANCE event and cease
+                                 recognition. It will return no more than one
+                                 SpeechRecognitionResult with the is_final flag
+                                 set to true.
+
+        :type interim_results: boolean
+        :param interim_results: [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.
+
+        :rtype: :class:`~streaming.StreamingResponseContainer`
+        :returns: An instance of ``StreamingReponseContainer``.
+
+        """
+        if not _USE_GAX:
+            raise EnvironmentError('GRPC is required to use this API.')
+
+        if sample.stream.closed:
+            raise ValueError('Stream is closed.')
+
+        requests = _make_request_stream(sample, language_code=language_code,
+                                        max_alternatives=max_alternatives,
+                                        profanity_filter=profanity_filter,
+                                        speech_context=speech_context,
+                                        single_utterance=single_utterance,
+                                        interim_results=interim_results)
+
+        responses = StreamingResponseContainer()
+        for response in self.speech_api.streaming_recognize(requests):
+            if response:
+                responses.add_response(response)
+
+        return responses
+
+    @property
+    def speech_api(self):
+        """Instance of Speech API.
+
+        :rtype: :class:`google.cloud.gapic.speech.v1beta1.speech_api.SpeechApi`
+        :returns: Instance of ``SpeechApi``.
+        """
+        if not self._speech_api:
+            self._speech_api = SpeechApi()
+        return self._speech_api
+
 
 def _build_request_data(sample, language_code=None, max_alternatives=None,
                         profanity_filter=None, speech_context=None):

speech/google/cloud/speech/operation.py

@@ -124,7 +124,8 @@ def _update(self, response):
         results = []
         if raw_results:
             for result in raw_results[0]['alternatives']:
-                results.append(Transcript(result))
+                results.append(Transcript(result.get('transcript'),
+                                          result.get('confidence')))
         if metadata:
             self._metadata = Metadata.from_api_repr(metadata)
 

speech/google/cloud/speech/sample.py

@@ -30,6 +30,9 @@ class Sample(object):
                        supported, which must be specified in the following
                        format: ``gs://bucket_name/object_name``.
 
+    :type stream: :class:`io.BufferedReader`
+    :param stream: File like object to read audio data from.
+
     :type encoding: str
     :param encoding: encoding of audio data sent in all RecognitionAudio
                      messages, can be one of: :attr:`~.Encoding.LINEAR16`,
@@ -47,16 +50,15 @@ class Sample(object):
     default_encoding = Encoding.FLAC
     default_sample_rate = 16000
 
-    def __init__(self, content=None, source_uri=None,
+    def __init__(self, content=None, source_uri=None, stream=None,
                  encoding=None, sample_rate=None):
-
-        no_source = content is None and source_uri is None
-        both_source = content is not None and source_uri is not None
-        if no_source or both_source:
-            raise ValueError('Supply one of \'content\' or \'source_uri\'')
+        if [content, source_uri, stream].count(None) != 2:
+            raise ValueError('Supply only one of \'content\', \'source_uri\''
+                             ' or stream.')
 
         self._content = content
         self._source_uri = source_uri
+        self._stream = stream
 
         if sample_rate is not None and not 8000 <= sample_rate <= 48000:
             raise ValueError('The value of sample_rate must be between 8000'
@@ -68,6 +70,15 @@ def __init__(self, content=None, source_uri=None,
         else:
             raise ValueError('Invalid encoding: %s' % (encoding,))
 
+    @property
+    def chunk_size(self):
+        """Chunk size to send over GRPC. ~100ms
+
+        :rtype: int
+        :returns: Optimized chunk size.
+        """
+        return int(self.sample_rate / 10)
+
     @property
     def source_uri(self):
         """Google Cloud Storage URI of audio source.
@@ -77,6 +88,15 @@ def source_uri(self):
         """
         return self._source_uri
 
+    @property
+    def stream(self):
+        """Stream of audio data.
+
+        :rtype: :class:`io.BufferedReader`
+        :returns: File like object to read audio data from.
+        """
+        return self._stream
+
     @property
     def content(self):
         """Bytes of audio content.