google-cloud-speech 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 83cf6bc0f6b7cda41a256f9e35d8d7b5d0cf1ecf
+  data.tar.gz: f5a81bafbd2102e775d329edb496457dd6ae81d8
+SHA512:
+  metadata.gz: fed9b104e7bbd9d1e01fb34095f2f6e495c2940727c474bf2d724a1e0341f7e179f2b8be81916f8f7449322eda03b7ff86cbdce3ca1f73b17ee3d9877699d0cf
+  data.tar.gz: 63b312ffd750b1ae643bb7246832455f85d7c37b21058a179644c6eefa694f38800076bd2b83d946dbd541bbc94b9f82153d034e7bc96e07b26326a37036cc8a

data/lib/google-cloud-speech.rb

@@ -0,0 +1,117 @@
+# 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.
+
+##
+# This file is here to be autorequired by bundler, so that the .speech and
+# #speech methods can be available, but the library and all dependencies won't
+# be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Speech service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/speech`
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. See Google::Gax::CallSettings. Optional.
+    #
+    # @return [Google::Cloud::Speech::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud = Google::Cloud.new
+    #   speech = gcloud.speech
+    #
+    #   audio = speech.audio "path/to/audio.raw",
+    #                        encoding: :raw, sample_rate: 16000
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+    #   speech = gcloud.speech scope: platform_scope
+    #
+    def speech scope: nil, timeout: nil, client_config: nil
+      Google::Cloud.speech @project, @keyfile, scope: scope,
+                                               timeout: (timeout || @timeout),
+                                               client_config: client_config
+    end
+
+    ##
+    # Creates a new object for connecting to the Speech service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String] project Project identifier for the Speech service you are
+    #   connecting to.
+    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+    #   file path the file must be readable.
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/speech`
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. See Google::Gax::CallSettings. Optional.
+    #
+    # @return [Google::Cloud::Speech::Project]
+    #
+    # @example
+    #   require "google/cloud/speech"
+    #
+    #   speech = Google::Cloud.speech
+    #
+    #   audio = speech.audio "path/to/audio.raw",
+    #                        encoding: :raw, sample_rate: 16000
+    #
+    def self.speech project = nil, keyfile = nil, scope: nil, timeout: nil,
+                    client_config: nil
+      require "google/cloud/speech"
+      project ||= Google::Cloud::Speech::Project.default_project
+      if keyfile.nil?
+        credentials = Google::Cloud::Speech::Credentials.default scope: scope
+      else
+        credentials = Google::Cloud::Speech::Credentials.new(
+          keyfile, scope: scope)
+      end
+      Google::Cloud::Speech::Project.new(
+        Google::Cloud::Speech::Service.new(
+          project, credentials, timeout: timeout, client_config: client_config))
+    end
+  end
+end

data/lib/google/cloud/speech.rb

@@ -0,0 +1,146 @@
+# 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"
+require "google/cloud/speech/project"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud Speech
+    #
+    # Google Cloud Speech API enables developers to convert audio to text by
+    # applying powerful neural network models in an easy to use API. The API
+    # recognizes over 80 languages and variants, to support your global user
+    # base. You can transcribe the text of users dictating to an application's
+    # microphone, enable command-and-control through voice, or transcribe audio
+    # files, among many other use cases. Recognize audio uploaded in the
+    # request, and integrate with your audio storage on Google Cloud Storage, by
+    # using the same technology Google uses to power its own products.
+    #
+    # For more information about Google Cloud Speech API, read the [Google Cloud
+    # Speech API Documentation](https://cloud.google.com/speech/docs/).
+    #
+    # The goal of google-cloud is to provide an API that is comfortable to
+    # Rubyists. Authentication is handled by {Google::Cloud#speech}. You can
+    # provide the project and credential information to connect to the Cloud
+    # Speech service, or if you are running on Google Compute Engine this
+    # configuration is taken care of for you. You can read more about the
+    # options for connecting in the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # ## Creating audio sources
+    #
+    # You can create an audio object that holds a reference to any one of
+    # several types of audio data source, along with metadata such as the audio
+    # encoding type.
+    #
+    # Use {Speech::Project#audio} to create audio sources for the Cloud Speech
+    # API. You can provide a file path:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # speech = gcloud.speech
+    #
+    # audio = speech.audio "path/to/audio.raw",
+    #                      encoding: :raw, sample_rate: 16000
+    # ```
+    #
+    # Or, you can initialize the audio instance with a Google Cloud Storage URI:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # speech = gcloud.speech
+    #
+    # audio = speech.audio "gs://bucket-name/path/to/audio.raw",
+    #                      encoding: :raw, sample_rate: 16000
+    # ```
+    #
+    # Or, with a Google Cloud Storage File object:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # storage = gcloud.storage
+    #
+    # bucket = storage.bucket "bucket-name"
+    # file = bucket.file "path/to/audio.raw"
+    #
+    # speech = gcloud.speech
+    #
+    # audio = speech.audio file, encoding: :raw, sample_rate: 16000
+    # ```
+    #
+    # ## Recognizing speech
+    #
+    # The instance methods on {Speech::Audio} can be used to invoke both
+    # synchronous and asynchronous versions of the Cloud Speech API speech
+    # recognition operation.
+    #
+    # Use {Speech::Audio#recognize} for synchronous speech recognition that
+    # returns {Result} objects only after all audio has been processed. This
+    # method is limited to audio data of 1 minute or less in duration, and will
+    # take roughly the same amount of time to process as the duration of the
+    # supplied audio data.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # speech = gcloud.speech
+    #
+    # audio = speech.audio "path/to/audio.raw",
+    #                      encoding: :raw, sample_rate: 16000
+    # results = audio.recognize
+    #
+    # result = results.first
+    # result.transcript #=> "how old is the Brooklyn Bridge"
+    # result.confidence #=> 88.15
+    # ```
+    #
+    # Use {Speech::Audio#recognize_job} for asynchronous speech recognition,
+    # in which a {Job} is returned immediately after the audio data has
+    # been sent. The job can be refreshed to retrieve {Result} objects
+    # once the audio data has been processed.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # speech = gcloud.speech
+    #
+    # 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
+    #
+    # result = results.first
+    # result.transcript #=> "how old is the Brooklyn Bridge"
+    # result.confidence #=> 88.15
+    # ```
+    #
+    module Speech
+    end
+  end
+end

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

@@ -0,0 +1,230 @@
+# 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.
+
+
+module Google
+  module Cloud
+    module Speech
+      ##
+      # # Audio
+      #
+      # Represents a source of audio data, with related metadata such as the
+      # [audio encoding](https://cloud.google.com/speech/docs/basics#audio-encodings),
+      # [sample rate](https://cloud.google.com/speech/docs/basics#sample-rates),
+      # and [language](https://cloud.google.com/speech/docs/basics#languages).
+      #
+      # See {Project#audio}.
+      #
+      # @see https://cloud.google.com/speech/docs/basics#audio-encodings
+      #   Audio Encodings
+      # @see https://cloud.google.com/speech/docs/basics#sample-rates
+      #   Sample Rates
+      # @see https://cloud.google.com/speech/docs/basics#languages
+      #   Languages
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   speech = gcloud.speech
+      #
+      #   audio = speech.audio "path/to/audio.raw",
+      #                        encoding: :raw, sample_rate: 16000
+      #   results = audio.recognize
+      #
+      #   result = results.first
+      #   result.transcript #=> "how old is the Brooklyn Bridge"
+      #   result.confidence #=> 88.15
+      #
+      class Audio
+        # @private The V1beta1::RecognitionAudio object.
+        attr_reader :grpc
+        # @private The Project object.
+        attr_reader :speech
+        attr_accessor :encoding
+        attr_accessor :sample_rate
+        attr_accessor :language
+
+        ##
+        # @private Creates a new Audio instance.
+        def initialize
+          @grpc = V1beta1::RecognitionAudio.new
+        end
+
+        ##
+        # @private Whether the Audio has content.
+        #
+        def content?
+          @grpc.audio_source == :content
+        end
+
+        ##
+        # @private Whether the Audio is a URL.
+        #
+        def url?
+          @grpc.audio_source == :uri
+        end
+
+        ##
+        # Performs synchronous speech recognition. Sends audio data to the
+        # Speech API, which performs recognition on that data, and returns
+        # results only after all audio has been processed. Limited to audio data
+        # of 1 minute or less in duration.
+        #
+        # The Speech API will take roughly the same amount of time to process
+        # audio data sent synchronously as the duration of the supplied audio
+        # data. That is, if you send audio data of 30 seconds in length, expect
+        # the synchronous request to take approximately 30 seconds to return
+        # results.
+        #
+        # @see https://cloud.google.com/speech/docs/basics#synchronous-recognition
+        #   Synchronous Speech API Recognition
+        # @see https://cloud.google.com/speech/docs/basics#phrase-hints
+        #   Phrase Hints
+        #
+        # @param [String] max_alternatives The Maximum number of recognition
+        #   hypotheses to be returned. Default is 1. The service may return
+        #   fewer. Valid values are 0-30. Defaults to 1. Optional.
+        # @param [Boolean] profanity_filter When `true`, the service will
+        #   attempt to filter out profanities, replacing all but the initial
+        #   character in each filtered word with asterisks, e.g. "f***". Default
+        #   is `false`.
+        # @param [Array<String>] phrases A list of strings containing words and
+        #   phrases "hints" so that the speech recognition is more likely to
+        #   recognize them. See [usage
+        #   limits](https://cloud.google.com/speech/limits#content). Optional.
+        #
+        # @return [Array<Result>] The transcribed text of audio recognized.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   speech = gcloud.speech
+        #
+        #   audio = speech.audio "path/to/audio.raw",
+        #                        encoding: :raw, sample_rate: 16000
+        #   results = audio.recognize
+        #
+        #   result = results.first
+        #   result.transcript #=> "how old is the Brooklyn Bridge"
+        #   result.confidence #=> 88.15
+        #
+        def recognize max_alternatives: nil, profanity_filter: nil, phrases: nil
+          ensure_speech!
+
+          speech.recognize self, encoding: encoding, sample_rate: sample_rate,
+                                 language: language,
+                                 max_alternatives: max_alternatives,
+                                 profanity_filter: profanity_filter,
+                                 phrases: phrases
+        end
+
+        ##
+        # 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.
+        #
+        # @see https://cloud.google.com/speech/docs/basics#async-responses
+        #   Asynchronous Speech API Responses
+        #
+        # @param [String] max_alternatives The Maximum number of recognition
+        #   hypotheses to be returned. Default is 1. The service may return
+        #   fewer. Valid values are 0-30. Defaults to 1. Optional.
+        # @param [Boolean] profanity_filter When `true`, the service will
+        #   attempt to filter out profanities, replacing all but the initial
+        #   character in each filtered word with asterisks, e.g. "f***". Default
+        #   is `false`.
+        # @param [Array<String>] phrases A list of strings containing words and
+        #   phrases "hints" so that the speech recognition is more likely to
+        #   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.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   speech = gcloud.speech
+        #
+        #   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
+          ensure_speech!
+
+          speech.recognize_job self, encoding: encoding,
+                                     sample_rate: sample_rate,
+                                     language: language,
+                                     max_alternatives: max_alternatives,
+                                     profanity_filter: profanity_filter,
+                                     phrases: phrases
+        end
+
+        ##
+        # @private The Google API Client object for the Audio.
+        def to_grpc
+          @grpc
+        end
+
+        ##
+        # @private New Audio from a source object.
+        def self.from_source source, speech
+          audio = new
+          audio.instance_variable_set :@speech, speech
+          if source.respond_to?(:read) && source.respond_to?(:rewind)
+            source.rewind
+            audio.grpc.content = source.read
+            return audio
+          end
+          # Convert Storage::File objects to the URL
+          source = source.to_gs_url if source.respond_to? :to_gs_url
+          # Everything should be a string from now on
+          source = String source
+          # Create an Audio from the Google Storage URL
+          if source.start_with? "gs://"
+            audio.grpc.uri = source
+            return audio
+          end
+          # Create an audio from a file on the filesystem
+          if File.file? source
+            fail ArgumentError, "Cannot read #{source}" unless \
+              File.readable? source
+            audio.grpc.content = File.read source, mode: "rb"
+            return audio
+          end
+          fail ArgumentError, "Unable to convert #{source} to an Audio"
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active Speech Project object is available.
+        def ensure_speech!
+          fail "Must have active connection" unless @speech
+        end
+      end
+    end
+  end
+end