google-cloud-speech 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e04f1437ef7d4bf55b73907f431f1195623a774d
-  data.tar.gz: 8dcd89edcce66e99b857b2191ae31a3ef7790561
+  metadata.gz: 36b97feadc80ff3fb73b37650feeb33ac875030f
+  data.tar.gz: 653975eca064e0e00a4d42c42b5296bdf5efd073
 SHA512:
-  metadata.gz: df413efa7c50545f37b0606e6015b446c6e4e9a940868fb16561b6d352bf9ba7d69a560bc4898ec5f5e145b94f5727183fc01ddc46e06066ec0c9d4a3e6bb58a
-  data.tar.gz: 39c89287e80db4ee918f14e20f89c3caff7d2b332881644b77a6838b7e41dadead53f7d44ae7d7f6c727d9ed78a93f8754c12fad1a3a52a8c7994dfe68ede62f
+  metadata.gz: e07b99125ff4f79b79a5676ebe0ba321a46d26ef7f27fe0f779a4676f91176520820ae5328c3e9f56324918745f95fa1399cab16b142bbc24aab06f1b1005b70
+  data.tar.gz: 5708a7d8aff0e3152179315ce5be6bb18bd04d0df5538f24ed822bfcd28e719aee436eaaea7dde3289f505f8136b7ae5a9232b9eafdd1e221b3b16565767eb0e

data/.yardopts

@@ -1,7 +1,5 @@
 --no-private
 --title=Google Cloud Speech
---exclude lib/google/cloud/speech/v1beta1
---exclude lib/google/cloud/speech/v1beta1.rb
 --markup markdown
 
 ./lib/**/*.rb

data/README.md

@@ -26,9 +26,11 @@ require "google/cloud/speech"
 speech = Google::Cloud::Speech.new
 
 audio = speech.audio "path/to/audio.raw",
-                     encoding: :raw, sample_rate: 16000
-results = audio.recognize
+                     encoding: :raw,
+                     language: "en-US",
+                     sample_rate: 16000
 
+results = audio.recognize
 result = results.first
 result.transcript #=> "how old is the Brooklyn Bridge"
 result.confidence #=> 0.9826789498329163

data/lib/google-cloud-speech.rb

@@ -51,7 +51,9 @@ module Google
     #   speech = gcloud.speech
     #
     #   audio = speech.audio "path/to/audio.raw",
-    #                        encoding: :raw, sample_rate: 16000
+    #                        encoding: :raw,
+    #                        language: "en-US",
+    #                        sample_rate: 16000
     #
     # @example The default scope can be overridden with the `scope` option:
     #   require "google/cloud"
@@ -97,7 +99,9 @@ module Google
     #   speech = Google::Cloud.speech
     #
     #   audio = speech.audio "path/to/audio.raw",
-    #                        encoding: :raw, sample_rate: 16000
+    #                        encoding: :raw,
+    #                        language: "en-US",
+    #                        sample_rate: 16000
     #
     def self.speech project = nil, keyfile = nil, scope: nil, timeout: nil,
                     client_config: nil

data/lib/google/cloud/speech.rb

@@ -56,7 +56,9 @@ module Google
     # speech = Google::Cloud::Speech.new
     #
     # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :raw, sample_rate: 16000
+    #                      encoding: :raw,
+    #                      language: "en-US",
+    #                      sample_rate: 16000
     # ```
     #
     # Or, you can initialize the audio instance with a Google Cloud Storage URI:
@@ -67,7 +69,9 @@ module Google
     # speech = Google::Cloud::Speech.new
     #
     # audio = speech.audio "gs://bucket-name/path/to/audio.raw",
-    #                      encoding: :raw, sample_rate: 16000
+    #                      encoding: :raw,
+    #                      language: "en-US",
+    #                      sample_rate: 16000
     # ```
     #
     # Or, with a Google Cloud Storage File object:
@@ -84,7 +88,10 @@ module Google
     #
     # speech = Google::Cloud::Speech.new
     #
-    # audio = speech.audio file, encoding: :raw, sample_rate: 16000
+    # audio = speech.audio file,
+    #                      encoding: :raw,
+    #                      language: "en-US",
+    #                      sample_rate: 16000
     # ```
     #
     # ## Recognizing speech
@@ -105,17 +112,19 @@ module Google
     # speech = Google::Cloud::Speech.new
     #
     # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :raw, sample_rate: 16000
-    # results = audio.recognize
+    #                      encoding: :raw,
+    #                      language: "en-US",
+    #                      sample_rate: 16000
     #
+    # results = audio.recognize
     # result = results.first
     # result.transcript #=> "how old is the Brooklyn Bridge"
     # result.confidence #=> 0.9826789498329163
     # ```
     #
-    # Use {Speech::Audio#recognize_job} for asynchronous speech recognition,
-    # in which a {Speech::Job} is returned immediately after the audio data has
-    # been sent. The job can be refreshed to retrieve {Speech::Result} objects
+    # Use {Speech::Audio#process} for asynchronous speech recognition, in which
+    # a {Speech::Operation} is returned immediately after the audio data has
+    # been sent. The op can be refreshed to retrieve {Speech::Result} objects
     # once the audio data has been processed.
     #
     # ```ruby
@@ -124,13 +133,15 @@ module Google
     # speech = Google::Cloud::Speech.new
     #
     # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :raw, sample_rate: 16000
-    # job = audio.recognize_job
+    #                      encoding: :raw,
+    #                      language: "en-US",
+    #                      sample_rate: 16000
     #
-    # job.done? #=> false
-    # job.reload!
-    # job.done? #=> true
-    # results = job.results
+    # op = audio.process
+    # op.done? #=> false
+    # op.wait_until_done!
+    # op.done? #=> true
+    # results = op.results
     #
     # result = results.first
     # result.transcript #=> "how old is the Brooklyn Bridge"
@@ -149,14 +160,9 @@ module Google
     #
     # audio = speech.audio "path/to/audio.raw"
     #
-    # stream = audio.stream encoding: :raw, sample_rate: 16000
-    #
-    # # register callback for when a result is returned
-    # stream.on_result do |results|
-    #   result = results.first
-    #   result.transcript #=> "how old is the Brooklyn Bridge"
-    #   result.confidence #=> 0.9826789498329163
-    # end
+    # stream = audio.stream encoding: :raw,
+    #                       language: "en-US",
+    #                       sample_rate: 16000
     #
     # # Stream 5 seconds of audio from the microphone
     # # Actual implementation of microphone input varies by platform
@@ -165,6 +171,12 @@ module Google
     # end
     #
     # stream.stop
+    # stream.wait_until_complete!
+    #
+    # results = stream.results
+    # result = results.first
+    # result.transcript #=> "how old is the Brooklyn Bridge"
+    # result.confidence #=> 0.9826789498329163
     # ```
     #
     # Obtaining audio data from input sources such as a Microphone is outside
@@ -203,7 +215,9 @@ module Google
       #   speech = Google::Cloud::Speech.new
       #
       #   audio = speech.audio "path/to/audio.raw",
-      #                        encoding: :raw, sample_rate: 16000
+      #                        encoding: :raw,
+      #                        language: "en-US",
+      #                        sample_rate: 16000
       #
       def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
                    client_config: nil

data/lib/google/cloud/speech/audio.rb

@@ -39,15 +39,17 @@ module Google
       #   speech = Google::Cloud::Speech.new
       #
       #   audio = speech.audio "path/to/audio.raw",
-      #                        encoding: :raw, sample_rate: 16000
-      #   results = audio.recognize
+      #                        encoding: :raw,
+      #                        language: "en-US",
+      #                        sample_rate: 16000
       #
+      #   results = audio.recognize
       #   result = results.first
       #   result.transcript #=> "how old is the Brooklyn Bridge"
       #   result.confidence #=> 0.9826789498329163
       #
       class Audio
-        # @private The V1beta1::RecognitionAudio object.
+        # @private The V1::RecognitionAudio object.
         attr_reader :grpc
         # @private The Project object.
         attr_reader :speech
@@ -69,6 +71,15 @@ module Google
         #     be 8000 Hz.) (AMR)
         #   * `amr_wb` - Adaptive Multi-Rate Wideband codec. (`sample_rate` must
         #     be 16000 Hz.) (AMR_WB)
+        #   * `ogg_opus` - Ogg Mapping for Opus. (OGG_OPUS)
+        #
+        #     Lossy codecs do not recommend, as they result in a lower-quality
+        #     speech transcription.
+        #   * `speex` - Speex with header byte. (SPEEX_WITH_HEADER_BYTE)
+        #
+        #     Lossy codecs do not recommend, as they result in a lower-quality
+        #     speech transcription. If you must use a low-bitrate encoder,
+        #     OGG_OPUS is preferred.
         #
         # @return [String,Symbol]
         #
@@ -78,17 +89,23 @@ module Google
         #   speech = Google::Cloud::Speech.new
         #
         #   audio = speech.audio "path/to/audio.raw",
-        #                        encoding: :raw, sample_rate: 16000
+        #                        language: "en-US",
+        #                        sample_rate: 16000
+        #
+        #   audio.encoding = :raw
+        #   audio.encoding #=> :raw
         #
         attr_accessor :encoding
 
         ##
-        # Sample rate in Hertz of the audio data to be recognized. 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).
+        # The language of the supplied audio as a
+        # [BCP-47](https://tools.ietf.org/html/bcp47) language code. e.g.
+        # "en-US" for English (United States), "en-GB" for English (United
+        # Kingdom), "fr-FR" for French (France). See [Language
+        # Support](https://cloud.google.com/speech/docs/languages) for a list of
+        # the currently supported language codes.
         #
-        # @return [Integer]
+        # @return [String,Symbol]
         #
         # @example
         #   require "google/cloud/speech"
@@ -96,18 +113,21 @@ module Google
         #   speech = Google::Cloud::Speech.new
         #
         #   audio = speech.audio "path/to/audio.raw",
-        #                        encoding: :raw, sample_rate: 16000
+        #                        encoding: :raw,
+        #                        sample_rate: 16000
         #
-        attr_accessor :sample_rate
+        #   audio.language = "en-US"
+        #   audio.language #=> "en-US"
+        #
+        attr_accessor :language
 
         ##
-        # The language of the supplied audio as a
-        # [BCP-47](https://tools.ietf.org/html/bcp47) language code.
-        # If not specified, the language defaults to "en-US".  See [Language
-        # Support](https://cloud.google.com/speech/docs/languages)
-        # for a list of the currently supported language codes.
+        # Sample rate in Hertz of the audio data to be recognized. 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).
         #
-        # @return [String,Symbol]
+        # @return [Integer]
         #
         # @example
         #   require "google/cloud/speech"
@@ -115,15 +135,18 @@ module Google
         #   speech = Google::Cloud::Speech.new
         #
         #   audio = speech.audio "path/to/audio.raw",
-        #                        encoding: :raw, sample_rate: 16000,
-        #                        language: :en
+        #                        encoding: :raw,
+        #                        language: "en-US"
         #
-        attr_accessor :language
+        #   audio.sample_rate = 16000
+        #   audio.sample_rate #=> 16000
+        #
+        attr_accessor :sample_rate
 
         ##
         # @private Creates a new Audio instance.
         def initialize
-          @grpc = V1beta1::RecognitionAudio.new
+          @grpc = V1::RecognitionAudio.new
         end
 
         ##
@@ -177,9 +200,11 @@ module Google
         #   speech = Google::Cloud::Speech.new
         #
         #   audio = speech.audio "path/to/audio.raw",
-        #                        encoding: :raw, sample_rate: 16000
-        #   results = audio.recognize
+        #                        encoding: :raw,
+        #                        language: "en-US",
+        #                        sample_rate: 16000
         #
+        #   results = audio.recognize
         #   result = results.first
         #   result.transcript #=> "how old is the Brooklyn Bridge"
         #   result.confidence #=> 0.9826789498329163
@@ -196,9 +221,9 @@ module Google
 
         ##
         # Performs asynchronous speech recognition. Requests are processed
-        # asynchronously, meaning a Job is returned once the audio data has been
-        # sent, and can be refreshed to retrieve recognition results once the
-        # audio data has been processed.
+        # asynchronously, meaning a Operation is returned once the audio data
+        # has been sent, and can be refreshed to retrieve recognition results
+        # once the audio data has been processed.
         #
         # @see https://cloud.google.com/speech/docs/basics#async-responses
         #   Asynchronous Speech API Responses
@@ -215,8 +240,8 @@ module Google
         #   recognize them. See [usage
         #   limits](https://cloud.google.com/speech/limits#content). Optional.
         #
-        # @return [Job] A resource represents the long-running, asynchronous
-        #   processing of a speech-recognition operation.
+        # @return [Operation] A resource represents the long-running,
+        #   asynchronous processing of a speech-recognition operation.
         #
         # @example
         #   require "google/cloud/speech"
@@ -224,25 +249,29 @@ module Google
         #   speech = Google::Cloud::Speech.new
         #
         #   audio = speech.audio "path/to/audio.raw",
-        #                        encoding: :raw, sample_rate: 16000
-        #   job = audio.recognize_job
-        #
-        #   job.done? #=> false
-        #   job.reload!
-        #   job.done? #=> true
-        #   results = job.results
-        #
-        def recognize_job max_alternatives: nil, profanity_filter: nil,
-                          phrases: nil
+        #                        encoding: :raw,
+        #                        language: "en-US",
+        #                        sample_rate: 16000
+        #
+        #   op = audio.process
+        #   op.done? #=> false
+        #   op.reload!
+        #   op.done? #=> true
+        #   results = op.results
+        #
+        def process max_alternatives: nil, profanity_filter: nil,
+                    phrases: nil
           ensure_speech!
 
-          speech.recognize_job self, encoding: encoding,
-                                     sample_rate: sample_rate,
-                                     language: language,
-                                     max_alternatives: max_alternatives,
-                                     profanity_filter: profanity_filter,
-                                     phrases: phrases
+          speech.process self, encoding: encoding,
+                               sample_rate: sample_rate,
+                               language: language,
+                               max_alternatives: max_alternatives,
+                               profanity_filter: profanity_filter,
+                               phrases: phrases
         end
+        alias_method :long_running_recognize, :process
+        alias_method :recognize_job, :process
 
         ##
         # @private The Google API Client object for the Audio.

data/lib/google/cloud/speech/credentials.rb

@@ -14,7 +14,7 @@
 
 
 require "google/cloud/credentials"
-require "google/cloud/speech/v1beta1"
+require "google/cloud/speech/v1"
 
 module Google
   module Cloud
@@ -22,7 +22,7 @@ module Google
       ##
       # @private Represents the OAuth 2.0 signing logic for Speech.
       class Credentials < Google::Cloud::Credentials
-        SCOPE = V1beta1::SpeechClient::ALL_SCOPES
+        SCOPE = V1::SpeechClient::ALL_SCOPES
         PATH_ENV_VARS = %w(SPEECH_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
         JSON_ENV_VARS = %w(SPEECH_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
                            GCLOUD_KEYFILE_JSON)

data/lib/google/cloud/speech/operation.rb

@@ -0,0 +1,262 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/speech/v1"
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module Speech
+      ##
+      # # Operation
+      #
+      # A resource represents the long-running, asynchronous processing of a
+      # speech-recognition operation. The op can be refreshed to retrieve
+      # recognition results once the audio data has been processed.
+      #
+      # See {Project#process} and {Audio#process}.
+      #
+      # @see https://cloud.google.com/speech/docs/basics#async-responses
+      #   Asynchronous Speech API Responses
+      # @see https://cloud.google.com/speech/reference/rpc/google.longrunning#google.longrunning.Operations
+      #   Long-running Operation
+      #
+      # @example
+      #   require "google/cloud/speech"
+      #
+      #   speech = Google::Cloud::Speech.new
+      #
+      #   op = speech.process "path/to/audio.raw",
+      #                              encoding: :raw,
+      #                              language: "en-US",
+      #                              sample_rate: 16000
+      #
+      #   op.done? #=> false
+      #   op.reload! # API call
+      #   op.done? #=> true
+      #   results = op.results
+      #
+      class Operation
+        ##
+        # @private The Google::Gax::Operation gRPC object.
+        attr_accessor :grpc
+
+        ##
+        # @private Creates a new Job instance.
+        def initialize
+          @grpc = nil
+        end
+
+        ##
+        # The unique identifier for the long running operation.
+        #
+        # @return [String] The unique identifier for the long running operation.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.id #=> "1234567890"
+        #
+        def id
+          @grpc.name
+        end
+
+        ##
+        # Checks if the speech-recognition processing of the audio data is
+        # complete.
+        #
+        # @return [boolean] `true` when complete, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> false
+        #
+        def done?
+          @grpc.done?
+        end
+
+        ##
+        # A speech recognition result corresponding to a portion of the audio.
+        #
+        # @return [Array<Result>] The transcribed text of audio recognized. If
+        #   the op is not done this will return `nil`.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> true
+        #   op.results? #=> true
+        #   results = op.results
+        #
+        def results
+          return nil unless results?
+          @grpc.response.results.map do |result_grpc|
+            Result.from_grpc result_grpc
+          end
+        end
+
+        ##
+        # Checks if the speech-recognition processing of the audio data is
+        # complete.
+        #
+        # @return [boolean] `true` when complete, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> true
+        #   op.results? #=> true
+        #   results = op.results
+        #
+        def results?
+          @grpc.response?
+        end
+
+        ##
+        # The error information if the speech-recognition processing of the
+        # audio data has returned an error.
+        #
+        # @return [Google::Cloud::Error] The error.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> true
+        #   op.error? #=> true
+        #   error = op.error
+        #
+        def error
+          return nil unless error?
+          Google::Cloud::Error.from_error @grpc.error
+        end
+
+        ##
+        # Checks if the speech-recognition processing of the audio data has
+        # returned an error.
+        #
+        # @return [boolean] `true` when errored, `false` otherwise.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> true
+        #   op.error? #=> true
+        #   error = op.error
+        #
+        def error?
+          @grpc.error?
+        end
+
+        ##
+        # Reloads the op with current data from the long-running, asynchronous
+        # processing of a speech-recognition operation.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> false
+        #   op.reload! # API call
+        #   op.done? #=> true
+        #
+        def reload!
+          @grpc.reload!
+          self
+        end
+        alias_method :refresh!, :reload!
+
+        ##
+        # Reloads the op until the operation is complete. The delay between
+        # reloads will incrementally increase.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   op = speech.process "path/to/audio.raw",
+        #                       encoding: :raw,
+        #                       language: "en-US",
+        #                       sample_rate: 16000
+        #
+        #   op.done? #=> false
+        #   op.wait_until_done!
+        #   op.done? #=> true
+        #
+        def wait_until_done!
+          @grpc.wait_until_done!
+        end
+
+        ##
+        # @private New Result::Job from a Google::Gax::Operation
+        # object.
+        def self.from_grpc grpc
+          new.tap do |job|
+            job.instance_variable_set :@grpc, grpc
+          end
+        end
+      end
+    end
+  end
+end