Merge pull request #2495 from daspecster/cleanup-speech

Updates from #2344 for speech API.

Author: daspecster

docs/index.rst

@@ -176,6 +176,7 @@
   speech-encoding
   speech-metadata
   speech-operation
+  speech-sample
   speech-transcript
 
 .. toctree::

docs/speech-sample.rst

@@ -0,0 +1,7 @@
+Speech Sample
+=============
+
+.. automodule:: google.cloud.speech.sample
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/speech-usage.rst

@@ -7,8 +7,8 @@ base.
 
 .. warning::
 
-   This is a Beta release of Google Speech API. This
-   API is not intended for real-time usage in critical applications.
+    This is a Beta release of Google Speech API. This
+    API is not intended for real-time usage in critical applications.
 
 .. _Google Speech: https://cloud.google.com/speech/docs/getting-started
 
@@ -25,10 +25,10 @@ For an overview of authentication in ``google-cloud-python``, see
 Assuming your environment is set up as described in that document,
 create an instance of :class:`~google.cloud.speech.client.Client`.
 
-  .. code-block:: python
+.. code-block:: python
 
-     >>> from google.cloud import speech
-     >>> client = speech.Client()
+    >>> from google.cloud import speech
+    >>> client = speech.Client()
 
 
 Asychronous Recognition
@@ -42,23 +42,27 @@ audio data of any duration up to 80 minutes.
 See: `Speech Asynchronous Recognize`_
 
 
-  .. code-block:: python
-
-      >>> import time
-      >>> operation = client.async_recognize(
-      ...     None, 'gs://my-bucket/recording.flac',
-      ...     'FLAC', 16000, max_alternatives=2)
-      >>> retry_count = 100
-      >>> while retry_count > 0 and not operation.complete:
-      ...     retry_count -= 1
-      ...     time.sleep(10)
-      ...     operation.poll()  # API call
-      >>> operation.complete
-      True
-      >>> operation.results[0].transcript
-      'how old is the Brooklyn Bridge'
-      >>> operation.results[0].confidence
-      0.98267895
+.. code-block:: python
+
+    >>> 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.FLAC,
+    ...                        sample_rate=44100)
+    >>> operation = client.async_recognize(sample, max_alternatives=2)
+    >>> retry_count = 100
+    >>> while retry_count > 0 and not operation.complete:
+    ...     retry_count -= 1
+    ...     time.sleep(10)
+    ...     operation.poll()  # API call
+    >>> operation.complete
+    True
+    >>> operation.results[0].transcript
+    'how old is the Brooklyn Bridge'
+    >>> operation.results[0].confidence
+    0.98267895
 
 
 Synchronous Recognition
@@ -67,11 +71,21 @@ Synchronous Recognition
 The :meth:`~google.cloud.speech.Client.sync_recognize` method converts speech
 data to text and returns alternative text transcriptons.
 
-  .. code-block:: python
+This example uses ``language_code='en-GB'`` to better recognize a dialect from
+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,
+    ...                        sample_rate=44100)
+    >>> operation = client.async_recognize(sample, max_alternatives=2)
      >>> alternatives = client.sync_recognize(
-     ...     None, 'gs://my-bucket/recording.flac',
-     ...     'FLAC', 16000, max_alternatives=2)
+     ...     'FLAC', 16000, source_uri='gs://my-bucket/recording.flac',
+     ...     language_code='en-GB', max_alternatives=2)
      >>> for alternative in alternatives:
      ...     print('=' * 20)
      ...     print('transcript: ' + alternative['transcript'])
@@ -83,5 +97,49 @@ data to text and returns alternative text transcriptons.
      transcript: Hello, this is one test
      confidence: 0
 
+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,
+    ...                        sample_rate=44100)
+    >>> alternatives = client.sync_recognize(sample, max_alternatives=1,
+    ...                                      profanity_filter=True)
+    >>> for alternative in alternatives:
+    ...     print('=' * 20)
+    ...     print('transcript: ' + alternative['transcript'])
+    ...     print('confidence: ' + alternative['confidence'])
+    ====================
+    transcript: Hello, this is a f****** test
+    confidence: 0.81
+
+Using speech context hints to get better results. 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.
+
+.. 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,
+    ...                        sample_rate=44100)
+    >>> hints = ['hi', 'good afternoon']
+    >>> alternatives = client.sync_recognize(sample, max_alternatives=2,
+    ...                                      speech_context=hints)
+    >>> for alternative in alternatives:
+    ...     print('=' * 20)
+    ...     print('transcript: ' + alternative['transcript'])
+    ...     print('confidence: ' + alternative['confidence'])
+    ====================
+    transcript: Hello, this is a test
+    confidence: 0.81
+
+
 .. _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

speech/google/cloud/speech/__init__.py

@@ -15,5 +15,4 @@
 """Google Cloud Speech API wrapper."""
 
 from google.cloud.speech.client import Client
-from google.cloud.speech.client import Encoding
 from google.cloud.speech.connection import Connection

speech/google/cloud/speech/client.py

@@ -19,8 +19,8 @@
 from google.cloud._helpers import _to_bytes
 from google.cloud import client as client_module
 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.sample import Sample
 
 
 class Client(client_module.Client):
@@ -46,39 +46,18 @@ class Client(client_module.Client):
 
     _connection_class = Connection
 
-    def async_recognize(self, content, source_uri, encoding, sample_rate,
-                        language_code=None, max_alternatives=None,
-                        profanity_filter=None, speech_context=None):
+    def async_recognize(self, sample, language_code=None,
+                        max_alternatives=None, profanity_filter=None,
+                        speech_context=None):
         """Asychronous Recognize request to Google Speech API.
 
         .. _async_recognize: https://cloud.google.com/speech/reference/\
                              rest/v1beta1/speech/asyncrecognize
 
         See `async_recognize`_.
 
-        :type content: bytes
-        :param content: Byte stream of audio.
-
-        :type source_uri: str
-        :param source_uri: URI that points to a file that contains audio
-                           data bytes as specified in RecognitionConfig.
-                           Currently, only Google Cloud Storage URIs are
-                           supported, which must be specified in the following
-                           format: ``gs://bucket_name/object_name``.
-
-        :type encoding: str
-        :param encoding: encoding of audio data sent in all RecognitionAudio
-                         messages, can be one of: :attr:`~.Encoding.LINEAR16`,
-                         :attr:`~.Encoding.FLAC`, :attr:`~.Encoding.MULAW`,
-                         :attr:`~.Encoding.AMR`, :attr:`~.Encoding.AMR_WB`
-
-        :type sample_rate: int
-        :param sample_rate: Sample rate in Hertz of the audio data sent in all
-                            requests. Valid values are: 8000-48000. 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).
+        :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
@@ -111,32 +90,25 @@ def async_recognize(self, content, source_uri, encoding, sample_rate,
         :returns: ``Operation`` for asynchronous request to Google Speech API.
         """
 
-        data = _build_request_data(content, source_uri, encoding,
-                                   sample_rate, language_code,
-                                   max_alternatives, profanity_filter,
-                                   speech_context)
+        data = _build_request_data(sample, language_code, max_alternatives,
+                                   profanity_filter, speech_context)
 
         api_response = self.connection.api_request(
             method='POST', path='speech:asyncrecognize', data=data)
 
         return Operation.from_api_repr(self, api_response)
 
-    def sync_recognize(self, content, source_uri, encoding, sample_rate,
-                       language_code=None, max_alternatives=None,
-                       profanity_filter=None, speech_context=None):
-        """Synchronous Speech Recognition.
-
-        .. _sync_recognize: https://cloud.google.com/speech/reference/\
-                            rest/v1beta1/speech/syncrecognize
-
-        See `sync_recognize`_.
+    @staticmethod
+    def sample(content=None, source_uri=None, encoding=None,
+               sample_rate=None):
+        """Factory: construct Sample to use when making recognize requests.
 
         :type content: bytes
-        :param content: Byte stream of audio.
+        :param content: (Optional) Byte stream of audio.
 
         :type source_uri: str
-        :param source_uri: URI that points to a file that contains audio
-                           data bytes as specified in RecognitionConfig.
+        :param source_uri: (Optional) URI that points to a file that contains
+                           audio data bytes as specified in RecognitionConfig.
                            Currently, only Google Cloud Storage URIs are
                            supported, which must be specified in the following
                            format: ``gs://bucket_name/object_name``.
@@ -155,6 +127,25 @@ def sync_recognize(self, content, source_uri, encoding, sample_rate,
                             native sample rate of the audio source (instead of
                             re-sampling).
 
+        :rtype: :class:`~google.cloud.speech.sample.Sample`
+        :returns: Instance of ``Sample``.
+        """
+        return Sample(content=content, source_uri=source_uri,
+                      encoding=encoding, sample_rate=sample_rate)
+
+    def sync_recognize(self, sample, language_code=None,
+                       max_alternatives=None, profanity_filter=None,
+                       speech_context=None):
+        """Synchronous Speech Recognition.
+
+        .. _sync_recognize: https://cloud.google.com/speech/reference/\
+                            rest/v1beta1/speech/syncrecognize
+
+        See `sync_recognize`_.
+
+        :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'``.
@@ -192,10 +183,8 @@ def sync_recognize(self, content, source_uri, encoding, sample_rate,
                     between 0 and 1.
         """
 
-        data = _build_request_data(content, source_uri, encoding,
-                                   sample_rate, language_code,
-                                   max_alternatives, profanity_filter,
-                                   speech_context)
+        data = _build_request_data(sample, language_code, max_alternatives,
+                                   profanity_filter, speech_context)
 
         api_response = self.connection.api_request(
             method='POST', path='speech:syncrecognize', data=data)
@@ -206,34 +195,12 @@ def sync_recognize(self, content, source_uri, encoding, sample_rate,
             raise ValueError('result in api should have length 1')
 
 
-def _build_request_data(content, source_uri, encoding, sample_rate,
-                        language_code=None, max_alternatives=None,
+def _build_request_data(sample, language_code=None, max_alternatives=None,
                         profanity_filter=None, speech_context=None):
     """Builds the request data before making API request.
 
-    :type content: bytes
-    :param content: Byte stream of audio.
-
-    :type source_uri: str
-    :param source_uri: URI that points to a file that contains audio
-                       data bytes as specified in RecognitionConfig.
-                       Currently, only Google Cloud Storage URIs are
-                       supported, which must be specified in the following
-                       format: ``gs://bucket_name/object_name``.
-
-    :type encoding: str
-    :param encoding: encoding of audio data sent in all RecognitionAudio
-                     messages, can be one of: :attr:`~.Encoding.LINEAR16`,
-                     :attr:`~.Encoding.FLAC`, :attr:`~.Encoding.MULAW`,
-                     :attr:`~.Encoding.AMR`, :attr:`~.Encoding.AMR_WB`
-
-    :type sample_rate: int
-    :param sample_rate: Sample rate in Hertz of the audio data sent in all
-                        requests. Valid values are: 8000-48000. 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).
+    :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
@@ -265,29 +232,13 @@ def _build_request_data(content, source_uri, encoding, sample_rate,
     :rtype: dict
     :returns: Dictionary with required data for Google Speech API.
     """
-    if content is None and source_uri is None:
-        raise ValueError('content and source_uri cannot be both '
-                         'equal to None')
-
-    if content is not None and source_uri is not None:
-        raise ValueError('content and source_uri cannot be both '
-                         'different from None')
-
-    if encoding is None:
-        raise ValueError('encoding cannot be None')
-
-    encoding_value = getattr(Encoding, encoding)
-
-    if sample_rate is None:
-        raise ValueError('sample_rate cannot be None')
-
-    if content is not None:
-        audio = {'content': b64encode(_to_bytes(content))}
+    if sample.content is not None:
+        audio = {'content': b64encode(_to_bytes(sample.content))}
     else:
-        audio = {'uri': source_uri}
+        audio = {'uri': sample.source_uri}
 
-    config = {'encoding': encoding_value,
-              'sampleRate': sample_rate}
+    config = {'encoding': sample.encoding,
+              'sampleRate': sample.sample_rate}
 
     if language_code is not None:
         config['languageCode'] = language_code