google-cloud-speech 0.29.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8413795f1ff1fc9d4cf12d6d60c49fe0239788fc150a7e2717fb0553659c53
-  data.tar.gz: 316185b6b5db45d5e7bdcf4ed800bbf06d39b049938d7e5b47502576a261a41f
+  metadata.gz: 763195f0925921b082ea312d0287d4ca43e57bcdba2348379b2a47df410be135
+  data.tar.gz: 30d926a0eecbe5a1a6aa70391d4b83db808425c96e69290171e1c1080ae6b533
 SHA512:
-  metadata.gz: 435c456d09e05127f99dceba69eca467cdef99101064668a1a888824d8b24eff2ccab37474c5ba801b5d797138fa9ceb9d9dbf5cc541384be0b178505e26e9bd
-  data.tar.gz: a766e0c9faf23aaa982cb0d5a1c9c5678d7b6227f09faf9de330c09bce559527d32e2a22e0bc1cac98b018e8d9aeb162ce534637161a3499bfcf25f876591155
+  metadata.gz: 7c32bacca6be56b87b96176b1b6dd9afde7910e5958ab7c264206cd34224889ceb6a2b708566eb1b409ef7c17b5a2f7ee23dac6b9d7f56db40ffc92db83a5ecc
+  data.tar.gz: 36157d4b83b244f712dfcecbab3a3ce13d7522e7175736c6b50c6234e2e8922d7569f521e71496a054544fcd8bbc0c9686059ba0086b0ab0576bab4a6da6b231

data/.yardopts

@@ -1,5 +1,6 @@
 --no-private
---title=Google Cloud Speech
+--title=Cloud Speech API
+--exclude _pb\.rb$
 --markup markdown
 
 ./lib/**/*.rb

data/LICENSE

@@ -1,4 +1,4 @@
-                                 Apache License
+                            Apache License
                            Version 2.0, January 2004
                         https://www.apache.org/licenses/
 

data/README.md

@@ -1,64 +1,90 @@
-# google-cloud-speech
+# Ruby Client for Cloud Speech API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
 
-[Google Cloud Speech API](https://cloud.google.com/speech/) ([docs](https://cloud.google.com/speech/docs)) enables developers to convert audio to text by applying powerful neural network models.
-
-- [google-cloud-speech API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-speech/latest)
-- [google-cloud-speech on RubyGems](https://rubygems.org/gems/google-cloud-speech)
-- [Google Cloud Speech API documentation](https://cloud.google.com/speech/docs)
+[Cloud Speech API][Product Documentation]:
+Converts audio to text by applying powerful neural network models.
+- [Client Library Documentation][]
+- [Product Documentation][]
 
 ## Quick Start
+In order to use this library, you first need to go through the following
+steps:
+
+1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+3. [Enable the Cloud Speech API.](https://console.cloud.google.com/apis/api/speech)
+4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
 
-```sh
+### Installation
+```
 $ gem install google-cloud-speech
 ```
 
-## Authentication
-
-This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables.
-
-Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-speech/guides/authentication).
+### Migration Guide
 
-## Example
+The 0.30.0 release introduced breaking changes relative to the previous release,
+0.29.0. For more details and instructions to migrate your code, please visit the
+[migration
+guide](https://cloud.google.com/speech-to-text/docs/ruby-client-migration).
 
-```ruby
+### Preview
+#### SpeechClient
+```rb
 require "google/cloud/speech"
 
-speech = Google::Cloud::Speech.new
-
-audio = speech.audio "path/to/audio.raw",
-                     encoding: :linear16,
-                     language: "en-US",
-                     sample_rate: 16000
-
-results = audio.recognize
-result = results.first
-result.transcript #=> "how old is the Brooklyn Bridge"
-result.confidence #=> 0.9826789498329163
+speech_client = Google::Cloud::Speech.new
+language_code = "en-US"
+sample_rate_hertz = 44100
+encoding = :FLAC
+config = {
+  language_code: language_code,
+  sample_rate_hertz: sample_rate_hertz,
+  encoding: encoding
+}
+uri = "gs://gapic-toolkit/hello.flac"
+audio = { uri: uri }
+response = speech_client.recognize(config, audio)
 ```
 
-## Supported Ruby Versions
-
-This library is supported on Ruby 2.0+.
-
-## Versioning
-
-This library follows [Semantic Versioning](http://semver.org/).
-
-It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.
+### Next Steps
+- Read the [Client Library Documentation][] for Cloud Speech API
+  to see other available methods on the client.
+- Read the [Cloud Speech API Product documentation][Product Documentation]
+  to learn more about the product and see How-to Guides.
+- View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+  to see the full list of Cloud APIs that we cover.
 
-## Contributing
+## Enabling Logging
 
-Contributions to this library are always welcome and highly encouraged.
+To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as shown below, or a [`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-logging/latest/google/cloud/logging/logger) that will write logs to [Stackdriver Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb) and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
 
-See the [Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing) for more information on how to get started.
+Configuring a Ruby stdlib logger:
 
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
+```ruby
+require "logger"
+
+module MyLogger
+  LOGGER = Logger.new $stderr, level: Logger::WARN
+  def logger
+    LOGGER
+  end
+end
+
+# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+module GRPC
+  extend MyLogger
+end
+```
 
-## License
+## Supported Ruby Versions
 
-This library is licensed under Apache 2.0. Full license text is available in [LICENSE](LICENSE).
+This library is supported on Ruby 2.0+.
 
-## Support
+However, Ruby 2.3 or later is strongly recommended, as earlier releases have
+reached or are nearing end-of-life. After June 1, 2018, Google will provide
+official support only for Ruby versions that are considered current and
+supported by Ruby Core (that is, Ruby versions that are either in normal
+maintenance or in security maintenance).
+See https://www.ruby-lang.org/en/downloads/branches/ for further details.
 
-Please [report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
-Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-cloud-ruby) about the client or APIs on [StackOverflow](http://stackoverflow.com).
+[Client Library Documentation]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-speech/latest/google/cloud/speech
+[Product Documentation]: https://cloud.google.com/speech

data/lib/google/cloud/speech.rb

@@ -1,4 +1,4 @@
-# Copyright 2016 Google LLC
+# Copyright 2018 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,281 +12,123 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
-require "google-cloud-speech"
-require "google/cloud/speech/project"
-require "google/cloud/config"
-require "google/cloud/env"
+require "google/gax"
+require "pathname"
 
 module Google
   module Cloud
+    # rubocop:disable LineLength
+
     ##
-    # # 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.
+    # # Ruby Client for Google Cloud Speech API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
     #
-    # For more information about Google Cloud Speech API, read the [Google Cloud
-    # Speech API Documentation](https://cloud.google.com/speech/docs/).
+    # [Google Cloud Speech API][Product Documentation]:
+    # Google Cloud Speech API.
+    # - [Product Documentation][]
     #
-    # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Your authentication credentials are detected automatically in
-    # Google Cloud Platform environments such as Google Compute Engine, Google
-    # App Engine and Google Kubernetes Engine. In other environments you can
-    # configure authentication easily, either directly in your code or via
-    # environment variables. Read more about the options for connecting in the
-    # [Authentication
-    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    # ## Quick Start
+    # In order to use this library, you first need to go through the following
+    # steps:
     #
-    # ## Creating audio sources
+    # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+    # 2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+    # 3. [Enable the Google Cloud Speech API.](https://console.cloud.google.com/apis/api/speech)
+    # 4. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
     #
-    # 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.
+    # ### Migration Guide
     #
-    # Use {Speech::Project#audio} to create audio sources for the Cloud Speech
-    # API. You can provide a file path:
+    # The 0.30.0 release introduced breaking changes relative to the previous
+    # release, 0.29.0. For more details and instructions to migrate your code,
+    # please visit the [migration
+    # guide](https://cloud.google.com/speech-to-text/docs/ruby-client-migration).
     #
-    # ```ruby
+    # ### Preview
+    # #### SpeechClient
+    # ```rb
     # require "google/cloud/speech"
     #
-    # speech = Google::Cloud::Speech.new
-    #
-    # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :linear16,
-    #                      language: "en-US",
-    #                      sample_rate: 16000
+    # speech_client = Google::Cloud::Speech.new
+    # language_code = "en-US"
+    # sample_rate_hertz = 44100
+    # encoding = :FLAC
+    # config = {
+    #   language_code: language_code,
+    #   sample_rate_hertz: sample_rate_hertz,
+    #   encoding: encoding
+    # }
+    # uri = "gs://gapic-toolkit/hello.flac"
+    # audio = { uri: uri }
+    # response = speech_client.recognize(config, audio)
     # ```
     #
-    # Or, you can initialize the audio instance with a Google Cloud Storage URI:
-    #
-    # ```ruby
-    # require "google/cloud/speech"
-    #
-    # speech = Google::Cloud::Speech.new
-    #
-    # audio = speech.audio "gs://bucket-name/path/to/audio.raw",
-    #                      encoding: :linear16,
-    #                      language: "en-US",
-    #                      sample_rate: 16000
-    # ```
+    # ### Next Steps
+    # - Read the [Google Cloud Speech API Product documentation][Product Documentation]
+    #   to learn more about the product and see How-to Guides.
+    # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+    #   to see the full list of Cloud APIs that we cover.
     #
-    # Or, with a Google Cloud Storage File object:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "bucket-name"
-    # file = bucket.file "path/to/audio.raw"
-    #
-    # require "google/cloud/speech"
-    #
-    # speech = Google::Cloud::Speech.new
-    #
-    # audio = speech.audio file,
-    #                      encoding: :linear16,
-    #                      language: "en-US",
-    #                      sample_rate: 16000
-    # ```
+    # [Product Documentation]: https://cloud.google.com/speech
     #
-    # ## 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 {Speech::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/speech"
-    #
-    # speech = Google::Cloud::Speech.new
-    #
-    # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :linear16,
-    #                      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#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
-    # require "google/cloud/speech"
-    #
-    # speech = Google::Cloud::Speech.new
-    #
-    # audio = speech.audio "path/to/audio.raw",
-    #                      encoding: :linear16,
-    #                      language: "en-US",
-    #                      sample_rate: 16000
-    #
-    # 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"
-    # result.confidence #=> 0.9826789498329163
-    # ```
-    #
-    # Use {Speech::Project#stream} for streaming audio data for speech
-    # recognition, in which a {Speech::Stream} is returned. The stream object
-    # can receive results while sending audio by performing bidirectional
-    # streaming speech-recognition.
-    #
-    # ```ruby
-    # require "google/cloud/speech"
-    #
-    # speech = Google::Cloud::Speech.new
-    #
-    # stream = speech.stream encoding: :linear16,
-    #                        language: "en-US",
-    #                        sample_rate: 16000
-    #
-    # # Stream 5 seconds of audio from the microphone
-    # # Actual implementation of microphone input varies by platform
-    # 5.times do
-    #   stream.send MicrophoneInput.read(32000)
-    # 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
-    # the scope of this document.
     #
     module Speech
-      ##
-      # 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_id Project identifier for the Speech service
-      #   you are connecting to. If not present, the default project for the
-      #   credentials is used.
-      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
-      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-      #   Google::Auth::Credentials object. (See {Speech::Credentials})
-      # @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. Optional.
-      # @param [String] project Alias for the `project_id` argument. Deprecated.
-      # @param [String] keyfile Alias for the `credentials` argument.
-      #   Deprecated.
-      #
-      # @return [Google::Cloud::Speech::Project]
-      #
-      # @example
-      #   require "google/cloud/speech"
-      #
-      #   speech = Google::Cloud::Speech.new
-      #
-      #   audio = speech.audio "path/to/audio.raw",
-      #                        encoding: :linear16,
-      #                        language: "en-US",
-      #                        sample_rate: 16000
-      #
-      def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
-                   client_config: nil, project: nil, keyfile: nil
-        project_id ||= (project || default_project_id)
-        project_id = project_id.to_s # Always cast to a string
-        raise ArgumentError, "project_id is missing" if project_id.empty?
+      # rubocop:enable LineLength
 
-        scope ||= configure.scope
-        timeout ||= configure.timeout
-        client_config ||= configure.client_config
-        credentials ||= (keyfile || default_credentials(scope: scope))
-        unless credentials.is_a? Google::Auth::Credentials
-          credentials = Speech::Credentials.new credentials, scope: scope
-        end
+      FILE_DIR = File.realdirpath(Pathname.new(__FILE__).join("..").join("speech"))
 
-        Speech::Project.new(
-          Speech::Service.new(
-            project_id, credentials, timeout: timeout,
-                                     client_config: client_config
-          )
-        )
-      end
+      AVAILABLE_VERSIONS = Dir["#{FILE_DIR}/*"]
+        .select { |file| File.directory?(file) }
+        .select { |dir| Google::Gax::VERSION_MATCHER.match(File.basename(dir)) }
+        .select { |dir| File.exist?(dir + ".rb") }
+        .map { |dir| File.basename(dir) }
 
       ##
-      # Configure the Google Cloud Speech library.
-      #
-      # The following Speech configuration parameters are supported:
-      #
-      # * `project_id` - (String) Identifier for a Speech project. (The
-      #   parameter `project` is considered deprecated, but may also be used.)
-      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
-      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-      #   Google::Auth::Credentials object. (See {Speech::Credentials}) (The
-      #   parameter `keyfile` is considered deprecated, but may also be used.)
-      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
-      #   the set of resources and operations that the connection can access.
-      # * `timeout` - (Integer) Default timeout to use in requests.
-      # * `client_config` - (Hash) A hash of values to override the default
-      #   behavior of the API client.
+      # Service that implements Google Cloud Speech API.
       #
-      # @return [Google::Cloud::Config] The configuration object the
-      #   Google::Cloud::Speech library uses.
-      #
-      def self.configure
-        yield Google::Cloud.configure.speech if block_given?
-
-        Google::Cloud.configure.speech
-      end
-
-      ##
-      # @private Default project.
-      def self.default_project_id
-        Google::Cloud.configure.speech.project_id ||
-          Google::Cloud.configure.project_id ||
-          Google::Cloud.env.project_id
-      end
+      # @param version [Symbol, String]
+      #   The major version of the service to be used. By default :v1
+      #   is used.
+      # @overload new(version:, credentials:, scopes:, client_config:, timeout:)
+      #   @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel, GRPC::Core::ChannelCredentials, Proc]
+      #     Provides the means for authenticating requests made by the client. This parameter can
+      #     be many types.
+      #     A `Google::Auth::Credentials` uses a the properties of its represented keyfile for
+      #     authenticating requests made by this client.
+      #     A `String` will be treated as the path to the keyfile to be used for the construction of
+      #     credentials for this client.
+      #     A `Hash` will be treated as the contents of a keyfile to be used for the construction of
+      #     credentials for this client.
+      #     A `GRPC::Core::Channel` will be used to make calls through.
+      #     A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials
+      #     should already be composed with a `GRPC::Core::CallCredentials` object.
+      #     A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the
+      #     metadata for requests, generally, to give OAuth credentials.
+      #   @param scopes [Array<String>]
+      #     The OAuth scopes for this service. This parameter is ignored if
+      #     an updater_proc is supplied.
+      #   @param client_config [Hash]
+      #     A Hash for call options for each method. See
+      #     Google::Gax#construct_settings for the structure of
+      #     this data. Falls back to the default config if not specified
+      #     or the specified config is missing data points.
+      #   @param timeout [Numeric]
+      #     The default timeout, in seconds, for calls made through this client.
+      #   @param metadata [Hash]
+      #     Default metadata to be sent with each request. This can be overridden on a per call basis.
+      #   @param exception_transformer [Proc]
+      #     An optional proc that intercepts any exceptions raised during an API call to inject
+      #     custom error handling.
+      def self.new(*args, version: :v1, **kwargs)
+        unless AVAILABLE_VERSIONS.include?(version.to_s.downcase)
+          raise "The version: #{version} is not available. The available versions " \
+            "are: [#{AVAILABLE_VERSIONS.join(", ")}]"
+        end
 
-      ##
-      # @private Default credentials.
-      def self.default_credentials scope: nil
-        Google::Cloud.configure.speech.credentials ||
-          Google::Cloud.configure.credentials ||
-          Speech::Credentials.default(scope: scope)
+        require "#{FILE_DIR}/#{version.to_s.downcase}"
+        version_module = Google::Cloud::Speech
+          .constants
+          .select {|sym| sym.to_s.downcase == version.to_s.downcase}
+          .first
+        Google::Cloud::Speech.const_get(version_module).new(*args, **kwargs)
       end
     end
   end