google-cloud-speech 0.20.0 → 0.21.0

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

@@ -35,14 +35,15 @@ module Google
       #   recognition is correct. This field is typically provided only for the
       #   top hypothesis. A value of 0.0 is a sentinel value indicating
       #   confidence was not set.
-      # @attr_reader [Array<Result>] alternatives Additional recognition
-      #   hypotheses (up to the value specified in `max_alternatives`).
+      # @attr_reader [Array<Result::Alternative>] alternatives Additional
+      #   recognition hypotheses (up to the value specified in
+      #   `max_alternatives`). The server may return fewer than
+      #   `max_alternatives`.
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/speech"
       #
-      #   gcloud = Google::Cloud.new
-      #   speech = gcloud.speech
+      #   speech = Google::Cloud::Speech.new
       #
       #   audio = speech.audio "path/to/audio.raw",
       #                        encoding: :raw, sample_rate: 16000
@@ -50,10 +51,7 @@ module Google
       #
       #   result = results.first
       #   result.transcript #=> "how old is the Brooklyn Bridge"
-      #   result.confidence #=> 88.15
-      #   alternative = result.alternatives.first
-      #   alternative.transcript #=> "how old is the Brooklyn brim"
-      #   alternative.confidence #=> 22.39
+      #   result.confidence #=> 0.9826789498329163
       #
       class Result
         attr_reader :transcript, :confidence, :alternatives
@@ -72,10 +70,126 @@ module Google
           head, *tail = *grpc.alternatives
           return nil if head.nil?
           alternatives = tail.map do |alt|
-            new alt.transcript, alt.confidence
+            Alternative.new alt.transcript, alt.confidence
           end
           new head.transcript, head.confidence, alternatives
         end
+
+        ##
+        # # Result::Alternative
+        #
+        # A speech recognition result corresponding to a portion of the audio.
+        #
+        # @attr_reader [String] transcript Transcript text representing the
+        #   words that the user spoke.
+        # @attr_reader [Float] confidence The confidence estimate between 0.0
+        #   and 1.0. A higher number means the system is more confident that the
+        #   recognition is correct. This field is typically provided only for
+        #   the top hypothesis. A value of 0.0 is a sentinel value indicating
+        #   confidence was not set.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   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 #=> 0.9826789498329163
+        #   alternative = result.alternatives.first
+        #   alternative.transcript #=> "how old is the Brooklyn brim"
+        #   alternative.confidence #=> 0.22030000388622284
+        #
+        class Alternative
+          attr_reader :transcript, :confidence
+
+          ##
+          # @private Creates a new Result::Alternative instance.
+          def initialize transcript, confidence
+            @transcript  = transcript
+            @confidence = confidence
+          end
+        end
+      end
+
+      ##
+      # # InterimResult
+      #
+      # A streaming speech recognition result corresponding to a portion of the
+      # audio that is currently being processed.
+      #
+      # See {Project#stream} and {Stream#on_interim}.
+      #
+      # @see https://cloud.google.com/speech/reference/rpc/google.cloud.speech.v1beta1#google.cloud.speech.v1beta1.SpeechRecognitionResult
+      #   SpeechRecognitionResult
+      # @see https://cloud.google.com/speech/reference/rpc/google.cloud.speech.v1beta1#google.cloud.speech.v1beta1.StreamingRecognitionResult
+      #   StreamingRecognitionResult
+      #
+      # @attr_reader [String] transcript Transcript text representing the words
+      #   that the user spoke.
+      # @attr_reader [Float] confidence The confidence estimate between 0.0 and
+      #   1.0. A higher number means the system is more confident that the
+      #   recognition is correct. This field is typically provided only for the
+      #   top hypothesis. A value of 0.0 is a sentinel value indicating
+      #   confidence was not set.
+      # @attr_reader [Float] stability An estimate of the probability that the
+      #   recognizer will not change its guess about this interim result. Values
+      #   range from 0.0 (completely unstable) to 1.0 (completely stable). Note
+      #   that this is not the same as confidence, which estimates the
+      #   probability that a recognition result is correct.
+      # @attr_reader [Array<Result::Alternative>] alternatives Additional
+      #   recognition hypotheses (up to the value specified in
+      #   `max_alternatives`).
+      #
+      # @example
+      #   require "google/cloud/speech"
+      #
+      #   speech = Google::Cloud::Speech.new
+      #
+      #   stream = audio.stream encoding: :raw, sample_rate: 16000
+      #
+      #   # register callback for when an interim result is returned
+      #   stream.on_interim do |final_results, interim_results|
+      #     interim_result = interim_results.first
+      #     puts interim_result.transcript # "how old is the Brooklyn Bridge"
+      #     puts interim_result.confidence # 0.9826789498329163
+      #     puts interim_result.stability # 0.8999
+      #   end
+      #
+      #   # Stream 5 seconds of audio from the microhone
+      #   # Actual implementation of microphone input varies by platform
+      #   5.times.do
+      #     stream.send MicrophoneInput.read(32000)
+      #   end
+      #
+      #   stream.stop
+      #
+      class InterimResult
+        attr_reader :transcript, :confidence, :stability, :alternatives
+
+        ##
+        # @private Creates a new InterimResult instance.
+        def initialize transcript, confidence, stability, alternatives = []
+          @transcript  = transcript
+          @confidence = confidence
+          @stability = stability
+          @alternatives = alternatives
+        end
+
+        ##
+        # @private New InterimResult from a StreamingRecognitionResult object.
+        def self.from_grpc grpc
+          head, *tail = *grpc.alternatives
+          return nil if head.nil?
+          alternatives = tail.map do |alt|
+            Result::Alternative.new alt.transcript, alt.confidence
+          end
+          new head.transcript, head.confidence, grpc.stability, alternatives
+        end
       end
     end
   end

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

@@ -39,11 +39,13 @@ module Google
         end
 
         def channel
+          require "grpc"
           GRPC::Core::Channel.new host, nil, chan_creds
         end
 
         def chan_creds
           return credentials if insecure?
+          require "grpc"
           GRPC::Core::ChannelCredentials.new.compose \
             GRPC::Core::CallCredentials.new credentials.client.updater_proc
         end
@@ -56,19 +58,21 @@ module Google
               channel: channel,
               timeout: timeout,
               client_config: client_config,
-              app_name: "google-cloud-speech",
+              app_name: "gcloud-ruby",
               app_version: Google::Cloud::Speech::VERSION)
         end
         attr_accessor :mocked_service
 
         def ops
           return mocked_ops if mocked_ops
-          @ops ||= begin
-            require "google/longrunning/operations_services_pb"
-
-            Google::Longrunning::Operations::Stub.new(
-              host, chan_creds, timeout: timeout)
-          end
+          @ops ||= \
+            Google::Longrunning::OperationsApi.new(
+              service_path: host,
+              channel: channel,
+              timeout: timeout,
+              client_config: client_config,
+              app_name: "gcloud-ruby",
+              app_version: Google::Cloud::Speech::VERSION)
         end
         attr_accessor :mocked_ops
 
@@ -77,16 +81,23 @@ module Google
         end
 
         def recognize_sync audio, config
-          execute { service.sync_recognize config, audio }
+          execute do
+            service.sync_recognize config, audio, options: default_options
+          end
         end
 
         def recognize_async audio, config
-          execute { service.async_recognize config, audio }
+          execute do
+            service.async_recognize config, audio, options: default_options
+          end
+        end
+
+        def recognize_stream request_enum
+          service.speech_stub.streaming_recognize request_enum
         end
 
         def get_op name
-          req = Google::Longrunning::GetOperationRequest.new name: name
-          execute { ops.get_operation req }
+          execute { ops.get_operation name }
         end
 
         def inspect
@@ -95,11 +106,19 @@ module Google
 
         protected
 
+        def default_headers
+          { "google-cloud-resource-prefix" => "projects/#{@project}" }
+        end
+
+        def default_options
+          Google::Gax::CallOptions.new kwargs: default_headers
+        end
+
         def execute
-          require "grpc" # Ensure GRPC is loaded before rescuing exception
           yield
-        rescue GRPC::BadStatus => e
-          raise Google::Cloud::Error.from_error(e)
+        rescue Google::Gax::GaxError => e
+          # GaxError wraps BadStatus, but exposes it as #cause
+          raise Google::Cloud::Error.from_error(e.cause)
         end
       end
     end

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

@@ -0,0 +1,563 @@
+# 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/v1beta1"
+require "google/cloud/speech/result"
+require "monitor"
+require "forwardable"
+
+module Google
+  module Cloud
+    module Speech
+      ##
+      # # Stream
+      #
+      # A resource that represents the streaming requests and responses.
+      #
+      # @example
+      #   require "google/cloud/speech"
+      #
+      #   speech = Google::Cloud::Speech.new
+      #
+      #   stream = audio.stream encoding: :raw, sample_rate: 16000
+      #
+      #   # register callback for when a result is returned
+      #   stream.on_result do |results|
+      #     result = results.first
+      #     puts result.transcript # "how old is the Brooklyn Bridge"
+      #     puts result.confidence # 0.9826789498329163
+      #   end
+      #
+      #   # Stream 5 seconds of audio from the microhone
+      #   # Actual implementation of microphone input varies by platform
+      #   5.times.do
+      #     stream.send MicrophoneInput.read(32000)
+      #   end
+      #
+      #   stream.stop
+      #
+      class Stream
+        include MonitorMixin
+        ##
+        # @private Creates a new Speech Stream instance.
+        # This must always be private, since it may change as the implementation
+        # changes over time.
+        def initialize service, streaming_recognize_request
+          @service = service
+          @streaming_recognize_request = streaming_recognize_request
+          @results = []
+          @callbacks = Hash.new { |h, k| h[k] = [] }
+          super() # to init MonitorMixin
+        end
+
+        ##
+        # Starts the stream. The stream will be started in the first #send call.
+        def start
+          return if @request_queue
+          @request_queue = EnumeratorQueue.new(self)
+          @request_queue.push @streaming_recognize_request
+
+          Thread.new { background_run }
+        end
+
+        ##
+        # Checks if the stream has been started.
+        #
+        # @return [boolean] `true` when started, `false` otherwise.
+        def started?
+          synchronize do
+            !(!@request_queue)
+          end
+        end
+
+        ##
+        # Sends audio content to the server.
+        #
+        # @param [String] bytes A string of binary audio data to be recognized.
+        #   The data should be encoded as `ASCII-8BIT`.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = speech.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when a result is returned
+        #   stream.on_result do |results|
+        #     result = results.first
+        #     puts result.transcript # "how old is the Brooklyn Bridge"
+        #     puts result.confidence # 0.9826789498329163
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def send bytes
+          start # lazily call start if the stream wasn't started yet
+          # TODO: do not send if stopped?
+          synchronize do
+            req = V1beta1::StreamingRecognizeRequest.new(
+              audio_content: bytes.encode("ASCII-8BIT"))
+            @request_queue.push req
+          end
+        end
+
+        ##
+        # Stops the stream. Signals to the server that no more data will be
+        # sent.
+        def stop
+          synchronize do
+            return if @request_queue.nil?
+            @request_queue.push self
+            @stopped = true
+          end
+        end
+
+        ##
+        # Checks if the stream has been stopped.
+        #
+        # @return [boolean] `true` when stopped, `false` otherwise.
+        def stopped?
+          synchronize do
+            @stopped
+          end
+        end
+
+        ##
+        # The speech recognition results for the audio.
+        #
+        # @return [Array<Result>] The transcribed text of audio recognized.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        #   results = stream.results
+        #   result = results.first
+        #   puts result.transcript # "how old is the Brooklyn Bridge"
+        #   puts result.confidence # 0.9826789498329163
+        #
+        def results
+          synchronize do
+            @results
+          end
+        end
+
+        ##
+        # Register to be notified on the reception of an interim result.
+        #
+        # @yield [callback] The block for accessing final and interim results.
+        # @yieldparam [Array<Result>] final_results The final results.
+        # @yieldparam [Array<Result>] interim_results The interim results.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when an interim result is returned
+        #   stream.on_interim do |final_results, interim_results|
+        #     interim_result = interim_results.first
+        #     puts interim_result.transcript # "how old is the Brooklyn Bridge"
+        #     puts interim_result.confidence # 0.9826789498329163
+        #     puts interim_result.stability # 0.8999
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_interim &block
+          synchronize do
+            @callbacks[:interim] << block
+          end
+        end
+
+        # @private yields two arguments, all final results and the
+        # non-final/incomplete result
+        def interim! interim_results
+          synchronize do
+            @callbacks[:interim].each { |c| c.call results, interim_results }
+          end
+        end
+
+        ##
+        # Register to be notified on the reception of a final result.
+        #
+        # @yield [callback] The block for accessing final results.
+        # @yieldparam [Array<Result>] results The final results.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when an interim result is returned
+        #   stream.on_result do |results|
+        #     result = results.first
+        #     puts result.transcript # "how old is the Brooklyn Bridge"
+        #     puts result.confidence # 0.9826789498329163
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_result &block
+          synchronize do
+            @callbacks[:result] << block
+          end
+        end
+
+        # @private add a result object, and call the callbacks
+        def add_result!result_index, result_grpc
+          synchronize do
+            @results[result_index] = Result.from_grpc result_grpc
+          end
+          # callback for final result received
+          result!
+        end
+
+        # @private yields each final results as they are recieved
+        def result!
+          synchronize do
+            @callbacks[:result].each { |c| c.call results }
+          end
+        end
+
+        ##
+        # Register to be notified when speech has been detected in the audio
+        # stream.
+        #
+        # @yield [callback] The block to be called when speech has been detected
+        #   in the audio stream.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when speech has started.
+        #   stream.on_speech_start do
+        #     puts "Speech has started."
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_speech_start &block
+          synchronize do
+            @callbacks[:speech_start] << block
+          end
+        end
+
+        # @private returns single final result once :END_OF_UTTERANCE is
+        # recieved.
+        def speech_start!
+          synchronize do
+            @callbacks[:speech_start].each(&:call)
+          end
+        end
+
+        ##
+        # Register to be notified when speech has ceased to be detected in the
+        # audio stream.
+        #
+        # @yield [callback] The block to be called when speech has ceased to be
+        #   detected in the audio stream.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when speech has ended.
+        #   stream.on_speech_end do
+        #     puts "Speech has ended."
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_speech_end &block
+          synchronize do
+            @callbacks[:speech_end] << block
+          end
+        end
+
+        # @private yields single final result once :END_OF_UTTERANCE is
+        # recieved.
+        def speech_end!
+          synchronize do
+            @callbacks[:speech_end].each(&:call)
+          end
+        end
+
+        ##
+        # Register to be notified when the end of the audio stream has been
+        # reached.
+        #
+        # @yield [callback] The block to be called when the end of the audio
+        #   stream has been reached.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when audio has ended.
+        #   stream.on_complete do
+        #     puts "Audio has ended."
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_complete &block
+          synchronize do
+            @callbacks[:complete] << block
+          end
+        end
+
+        # @private yields all final results once the recognition is completed
+        # depending on how the Stream is configured, this can be on the
+        # reception of :END_OF_AUDIO or :END_OF_UTTERANCE.
+        def complete!
+          synchronize do
+            @callbacks[:complete].each(&:call)
+          end
+        end
+
+        ##
+        # Register to be notified when the server has detected the end of the
+        # user's speech utterance and expects no additional speech. Therefore,
+        # the server will not process additional audio. The client should stop
+        # sending additional audio data. This event only occurs when `utterance`
+        # is `true`.
+        #
+        # @yield [callback] The block to be called when the end of the audio
+        #   stream has been reached.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw,
+        #                         sample_rate: 16000,
+        #                         utterance: true
+        #
+        #   # register callback for when utterance has occurred.
+        #   stream.on_utterance do
+        #     puts "Utterance has occurred."
+        #     stream.stop
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop unless stream.stopped?
+        #
+        def on_utterance &block
+          synchronize do
+            @callbacks[:utterance] << block
+          end
+        end
+
+        # @private returns single final result once :END_OF_UTTERANCE is
+        # recieved.
+        def utterance!
+          synchronize do
+            @callbacks[:utterance].each(&:call)
+          end
+        end
+
+        ##
+        # Register to be notified of an error recieved during the stream.
+        #
+        # @yield [callback] The block for accessing final results.
+        # @yieldparam [Exception] error The error raised.
+        #
+        # @example
+        #   require "google/cloud/speech"
+        #
+        #   speech = Google::Cloud::Speech.new
+        #
+        #   stream = audio.stream encoding: :raw, sample_rate: 16000
+        #
+        #   # register callback for when an error is returned
+        #   stream.on_error do |error|
+        #     puts "The following error occurred while streaming: #{error}"
+        #     stream.stop
+        #   end
+        #
+        #   # Stream 5 seconds of audio from the microhone
+        #   # Actual implementation of microphone input varies by platform
+        #   5.times.do
+        #     stream.send MicrophoneInput.read(32000)
+        #   end
+        #
+        #   stream.stop
+        #
+        def on_error &block
+          synchronize do
+            @callbacks[:error] << block
+          end
+        end
+
+        # @private returns error object from the stream thread.
+        def error! err
+          synchronize do
+            @callbacks[:error].each { |c| c.call err }
+          end
+        end
+
+        protected
+
+        def background_run
+          response_enum = @service.recognize_stream @request_queue.each_item
+          response_enum.each do |response|
+            begin
+              background_results response
+              background_endpointer response.endpointer_type
+              background_error response.error
+            rescue => e
+              error! Google::Cloud::Error.from_error(e)
+            end
+          end
+          Thread.pass
+        end
+
+        def background_results response
+          # Handle the results (StreamingRecognitionResult)
+          return unless response.results && response.results.any?
+
+          final_grpc, interim_grpcs = *response.results
+          if final_grpc && final_grpc.is_final
+            add_result! response.result_index, final_grpc
+          else
+            # all results are interim
+            interim_grpcs = response.results
+          end
+
+          # convert to Speech object from GRPC object
+          interim_results = Array(interim_grpcs).map do |grpc|
+            InterimResult.from_grpc grpc
+          end
+          # callback for interim results received
+          interim! interim_results if interim_results.any?
+        end
+
+        def background_endpointer endpointer
+          # Handle the endpointer by raising events
+          if endpointer == :START_OF_SPEECH
+            speech_start!
+          elsif endpointer == :END_OF_SPEECH
+            speech_end!
+          elsif endpointer == :END_OF_AUDIO
+            # TODO: do we automatically call stop here?
+            complete!
+          elsif endpointer == :END_OF_UTTERANCE
+            # TODO: do we automatically call stop here?
+            utterance!
+          end
+        end
+
+        def background_error error
+          return if error.nil?
+
+          require "grpc/errors"
+          fail GRPC::BadStatus.new(error.code, error.message)
+        end
+
+        # @private
+        class EnumeratorQueue
+          extend Forwardable
+          def_delegators :@q, :push
+
+          # @private
+          def initialize sentinel
+            @q = Queue.new
+            @sentinel = sentinel
+          end
+
+          # @private
+          def each_item
+            return enum_for(:each_item) unless block_given?
+            loop do
+              r = @q.pop
+              break if r.equal? @sentinel
+              fail r if r.is_a? Exception
+              yield r
+            end
+          end
+        end
+      end
+    end
+  end
+end