Add Speech Streaming API.

docs/index.rst

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

docs/speech-streaming.rst

@@ -0,0 +1,15 @@
+Streaming Speech Response
+=========================
+
+.. automodule:: google.cloud.speech.streaming_response
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Streaming Speech Result
+=======================
+
+.. automodule:: google.cloud.speech.streaming_result
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/speech-usage.rst

@@ -51,10 +51,9 @@ See: `Speech Asynchronous Recognize`_
 
     >>> import time
     >>> from google.cloud import speech
-    >>> from google.cloud.speech.encoding import Encoding
     >>> client = speech.Client()
     >>> sample = client.sample(source_uri='gs://my-bucket/recording.flac',
-    ...                        encoding=Encoding.LINEAR16,
+    ...                        encoding=speech.Encoding.LINEAR16,
     ...                        sample_rate=44100)
     >>> operation = client.async_recognize(sample, max_alternatives=2)
     >>> retry_count = 100
@@ -82,10 +81,9 @@ Great Britian.
 .. code-block:: python
 
     >>> from google.cloud import speech
-    >>> from google.cloud.speech.encoding import Encoding
     >>> client = speech.Client()
     >>> sample = client.sample(source_uri='gs://my-bucket/recording.flac',
-    ...                        encoding=Encoding.FLAC,
+    ...                        encoding=speech.Encoding.FLAC,
     ...                        sample_rate=44100)
     >>> operation = client.async_recognize(sample, max_alternatives=2)
      >>> alternatives = client.sync_recognize(
@@ -107,10 +105,9 @@ Example of using the profanity filter.
 .. code-block:: python
 
     >>> from google.cloud import speech
-    >>> from google.cloud.speech.encoding import Encoding
     >>> client = speech.Client()
     >>> sample = client.sample(source_uri='gs://my-bucket/recording.flac',
-    ...                        encoding=Encoding.FLAC,
+    ...                        encoding=speech.Encoding.FLAC,
     ...                        sample_rate=44100)
     >>> alternatives = client.sync_recognize(sample, max_alternatives=1,
     ...                                      profanity_filter=True)
@@ -129,10 +126,9 @@ words to the vocabulary of the recognizer.
 .. code-block:: python
 
     >>> from google.cloud import speech
-    >>> from google.cloud.speech.encoding import Encoding
     >>> client = speech.Client()
     >>> sample = client.sample(source_uri='gs://my-bucket/recording.flac',
-    ...                        encoding=Encoding.FLAC,
+    ...                        encoding=speech.Encoding.FLAC,
     ...                        sample_rate=44100)
     >>> hints = ['hi', 'good afternoon']
     >>> alternatives = client.sync_recognize(sample, max_alternatives=2,
@@ -145,5 +141,81 @@ 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
+
+.. code-block:: python
+
+    >>> from google.cloud import speech
+    >>> client = speech.Client()
+    >>> with open('./hello.wav', 'rb') as stream:
+    ...     sample = client.sample(stream=stream, encoding=speech.Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    ...     for response in client.stream_recognize(sample):
+    ...         print(response.transcript)
+    ...         print(response.is_final)
+    hello
+    True
+
+
+By setting ``interim_results`` to :data:`True`, interim results (tentative hypotheses)
+may be returned as they become available (these interim results are indicated
+with the ``is_final=false`` flag). If :data:`False` or omitted, only ``is_final=true``
+result(s) are returned.
+
+.. code-block:: python
+
+    >>> from google.cloud import speech
+    >>> client = speech.Client()
+    >>> with open('./hello.wav', 'rb') as stream:
+    ...     sample = client.sample(stream=stream, encoding=speech.Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    ...     for response in client.stream_recognize(sample,
+    ...                                             interim_results=True):
+    ...         print('====Response====')
+    ...         print(response.transcript)
+    ...         print(response.is_final)
+    ====Response====
+    he
+    False
+    ====Response====
+    hell
+    False
+    ====Repsonse====
+    hello
+    True
+
+
+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 open('./hello_pause_goodbye.wav', 'rb') as stream:
+    ...     sample = client.sample(stream=stream, encoding=speech.Encoding.LINEAR16,
+    ...                            sample_rate=16000)
+    ...     for response in client.stream_recognize(sample,
+    ...                                             single_utterance=True):
+    ...         print(response.transcript)
+    ...         print(response.is_final)
+    hello
+    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

@@ -44,6 +44,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/__init__.py

@@ -16,3 +16,4 @@
 
 from google.cloud.speech.client import Client
 from google.cloud.speech.connection import Connection
+from google.cloud.speech.encoding import Encoding