voice_id 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a5036968c4e311ca99e004aa99ca522b7e18e95
+  data.tar.gz: 7fc7ff2b2ec9e1733f9c7894dae6f9aad06aff68
+SHA512:
+  metadata.gz: a1e5a759472231990225bf5274693f0e688874a73d557618bad5d74fa8952462f5055b88b7f60ae66cf6a26cbd030331873eff3cbad35561de2d1ff715f500d7
+  data.tar.gz: 9e8df1b131c889f843e5f64c6508e7c18a7773370cdc9201d6c2a7b17df3b89129261ab9e3be2a37d4d51c2ae9227a5df67834a0e1b997a7b429b61a50d4eb60

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016- Ali Yazdani <aliyazdani82@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Readme.md

@@ -0,0 +1,277 @@
+![](https://img.shields.io/badge/license-MIT-blue.svg)
+[![CircleCI](https://circleci.com/gh/aliyazdani/voice_id.svg?style=svg)](https://circleci.com/gh/aliyazdani/voice_id)
+
+# VoiceId
+  Wrapper around Microsoft Cognitive Services - Speaker Recognition API
+
+## Installation
+  sign up and pick up a new api key (speaker recognition API key) 
+  [https://www.microsoft.com/cognitive-services](https://www.microsoft.com/cognitive-services)
+
+  ```
+  $ gem install voice_id
+  ```
+
+## Examples
+  
+
+```ruby
+  #create a new profile
+  identification = VoiceId::Identification.new("MS_speaker_recognition_api_key")
+  profile        = identification.create_profile
+  # => { "identificationProfileId" => "49a46324-fc4b-4387-aa06-090cfbf0214f" }
+
+  # create a new enrollment for that profile
+  profile_id    = profile["identificationProfileId"]
+  path_to_audio = '/path/to/some/audio_file.wav'
+  short_audio   = true
+  operation_url = identification.create_enrollment(profile_id , short_audio, path_to_audio)
+  # => "https://api.projectoxford.ai/spid/v1.0/operations/EF217D0C-9085-45D7-AAE0-2B36471B89B5"
+
+  # check the status of operation
+  operation_id = identification.get_operation_id(operation_url)
+  # => "EF217D0C-9085-45D7-AAE0-2B36471B89B5"
+
+  identification.get_operation_status(operation_id)
+  # notice below that we only had 13.6 seconds of useable audio so we need to
+  # submit more enrollments for this profile until we achieve at min 30 seconds
+  # => 
+  #   {
+  #    "status" => "succeeded", 
+  #    "createdDateTime" => "2016-09-23T01:34:44.226642Z",
+  #    "lastActionDateTime" => "2016-09-23T01:34:44.4795299Z",
+  #    "processingResult" => {
+  #      "enrollmentStatus" => "Enrolling", 
+  #      "remainingEnrollmentSpeechTime" => 16.4, 
+  #      "speechTime" => 13.6, 
+  #      "enrollmentSpeechTime"=>13.6
+  #    }
+  #   }
+
+  # identify a speaker
+  profile_ids                  = ["49a46324-fc4b-4387-aa06-090cfbf0214f", "49a36324-fc4b-4387-aa06-091cfbf0216b", ...]
+  path_to_test_audio           = '/path/to/some/audio_file.wav'
+  short_audio                  = true
+  identification_operation_url = identification.identify_speaker(profile_ids, short_audio, path_to_test_audio)
+  # => "https://api.projectoxford.ai/spid/v1.0/operations/EF217D0C-9085-45D7-AAE0-2B36471B89B6"
+  identification_operation_id = identification.get_operation_id(identification_operation_url)
+  # => "EF217D0C-9085-45D7-AAE0-2B36471B89B6"
+  identification.get_operation_status(identification_operation_id)
+  # => 
+  # {
+  #  "status" => "succeeded", 
+  #  "createdDateTime" => "2016-09-23T02:01:54.6498703Z",
+  #  "lastActionDateTime" => "2016-09-23T02:01:56.054633Z",
+  #  "processingResult" => {
+  #    "identifiedProfileId" => "49a46324-fc4b-4387-aa06-090cfbf0214f", 
+  #    "confidence"=>"High"
+  #   }
+  # }
+```
+
+## APIs
+  Provides methods for two APIs (Identification and Verification)
+  All audio samples provided to the API must be the following format:
+  ```
+  Container WAV
+  Encoding  PCM
+  Rate  16K
+  Sample Format 16 bit
+  Channels  Mono
+  ```
+
+### Identification API
+Identify a person from a list of people - this is a text-independant api.
+Prior to being able to identify a speaker, a speaker (profile) must send a minimum
+of 30 seconds of recognizable audio.
+```ruby
+identification = VoiceId::Identification.new("MS_speaker_recognition_api_key")
+```
+
+#### create_profile
+Each person needs a unique profile, this creates a new one.
+```ruby
+  profile = identification.create_profile
+  # => { "identificationProfileId" => "49a36324-fc4b-4387-aa06-090cfbf0064f" }
+```
+
+#### create_enrollment(profile_id, short_audio, audio_file_path)
+An enrollment is how audio samples are associated with a profile (training the service).  For the Identification API a minimum of 30 seconds of recognizable speach is required.  This can be done through multiple enrollments.  This creates a new
+enrollment for a profile.
+
+```ruby
+  profile_id    = "1234567890"
+  path_to_audio = '/path/to/some/audio_file.wav'
+  short_audio   = true # true - set minimum duration to 1 sec (5 sec by default per enrollment)
+  identification.create_enrollment(profile_id, short_audio, path_to_audio)
+  # returns an operation url that you can use to check the status of the enrollment
+  # => "https://api.projectoxford.ai/spid/v1.0/operations/EF217D0C-9085-45D7-AAE0-2B36471B89B5"
+```
+#### get_operation_id(operation_status_url)
+Certain endpoints take time to process to they return a url for you to check on the status of the operation.  To parse out the operation id use this method.  Now you can use #get_operation_status to
+check the id.
+```ruby
+  operation_status_url = identification.create_enrollment(profile_id, short_audio, path_to_audio)
+  # => "https://api.projectoxford.ai/spid/v1.0/operations/EF217D0C-9085-45D7-AAE0-2B36471B89B5"
+  identification_operation_id = identification.get_operation_id(operation_status_url)
+  # => "EF217D0C-9085-45D7-AAE0-2B36471B89B6"
+```
+#### get_operation_status(operation_id)
+Check on the status of an operation by passing in the operation id (use #get_operation_id to get the id)
+```ruby
+  identification.get_operation_status(identification_operation_id)
+  # => 
+  # {
+  #  "status" => "succeeded", 
+  #  "createdDateTime" => "2016-09-23T02:01:54.6498703Z",
+  #  "lastActionDateTime" => "2016-09-23T02:01:56.054633Z",
+  #  "processingResult" => {
+  #    "identifiedProfileId" => "49a59333-ur9d-4387-wd06-880cfby0215f", 
+  #    "confidence"=>"High"
+  #   }
+  # }
+```
+
+#### delete_profile(profile_id)
+Delete a particular profile from the service.
+```ruby
+  profile_id = "1234567890"
+  identification.delete_profile(profile_id)
+  # => true
+```
+
+#### get_all_profiles
+Returns a list of all the profiles for this account.
+```ruby
+    identification.get_all_profiles
+    # => 
+    # [
+    #   {
+    #     "identificationProfileId" => "111f427c-3791-468f-b709-fcef7660fff9",
+    #     "locale" => "en-US",
+    #     "enrollmentSpeechTime" => 0.0
+    #     "remainingEnrollmentSpeechTime" => 0.0,
+    #     "createdDateTime" => "2015-04-23T18:25:43.511Z",
+    #     "lastActionDateTime" => "2015-04-23T18:25:43.511Z",
+    #     "enrollmentStatus" => "Enrolled" //[Enrolled | Enrolling | Training]
+    #   }, ...
+    # ]
+```
+
+#### get_profile(profileId)
+Returns a profile's details
+```ruby
+  profile_id = "1234567890"
+  identification.get_profile(profile_id)
+  # =>
+  #   {
+  #     "identificationProfileId" => "111f427c-3791-468f-b709-fcef7660fff9",
+  #     "locale" => "en-US",
+  #     "enrollmentSpeechTime" => 0.0,
+  #     "remainingEnrollmentSpeechTime" => 0.0,
+  #     "createdDateTime" => "2015-04-23T18:25:43.511Z",
+  #     "lastActionDateTime" => "2015-04-23T18:25:43.511Z",
+  #     "enrollmentStatus" => "Enrolled" //[Enrolled | Enrolling | Training]
+  #   }
+```
+
+#### reset_all_enrollments_for_profile(profileId)
+Resets all the enrollments for a particular profile
+```ruby
+  profile_id = "1234567890"
+  identification.reset_all_enrollments_for_profile(profile_id)
+  # => true
+```
+
+#### identify_speaker(profile_ids, short_audio, audio_file_path)
+Identify a speaker by calling this method with an array of `enrolled` profile_ids.
+Use ```short_audio``` to wave the required 5-second speech sample.
+The audio sample to be analyzed should ideally be 30 seconds, with a maximum of 5 mins.
+
+```ruby
+  profile_ids        = ["49a46324-fc4b-4387-aa06-090cfbf0214f", "49a36324-fc4b-4387-aa06-091cfbf0216b", ...]
+  path_to_test_audio = '/path/to/some/audio_file.wav'
+  short_audio        = true
+  operation_url      = identification.identify_speaker(profile_ids, short_audio, path_to_test_audio)
+  # => "https://api.projectoxford.ai/spid/v1.0/operations/EF217D0C-9085-45D7-AAE0-2B36471B89B6"
+  identification_operation_id = identification.get_operation_id(operation_url)
+  # => "EF217D0C-9085-45D7-AAE0-2B36471B89B6"
+  identification.get_operation_status(identification_operation_id)
+  # => 
+  # {
+  #  "status" => "succeeded", 
+  #  "createdDateTime" => "2016-09-23T02:01:54.6498703Z",
+  #  "lastActionDateTime" => "2016-09-23T02:01:56.054633Z",
+  #  "processingResult" => {
+  #    "identifiedProfileId" => "49a46324-fc4b-4387-aa06-090cfbf0214f", 
+  #    "confidence"=>"High"
+  #   }
+  # }
+``` 
+
+### Verification API
+Verify that a person is who they say they are - this is a text-dependent api.
+Prior to being able to verify a speaker, a speaker (profile) must send three audio samples (from an API provided list) with their enrollment.
+```ruby
+verification = VoiceId::Verification.new("MS_speaker_recognition_api_key")
+```
+
+#### list_all_verification_phrases
+Get a list of accepted scripts to use when sending your audio sample.
+```ruby
+  verification.list_all_verification_phrases
+  # =>
+  #  [
+  #   {"phrase" => "i am going to make him an offer he cannot refuse"}, 
+  #   {"phrase" => "houston we have had a problem"}, 
+  #   {"phrase" => "my voice is my passport verify me"}, 
+  #   {"phrase" => "apple juice tastes funny after toothpaste"}, 
+  #   {"phrase" => "you can get in without your password"}, 
+  #   {"phrase" => "you can activate security system now"}, 
+  #   {"phrase" => "my voice is stronger than passwords"}, 
+  #   {"phrase" => "my password is not your business"}, 
+  #   {"phrase" => "my name is unknown to you"}, 
+  #   {"phrase" => "be yourself everyone else is already taken"}
+  #  ]
+```
+
+#### create_profile
+Same as Identification API
+
+#### create_enrollment(profile_id, audio_file_path)
+Requires 3 enrollments.  Pick 3 of the acceptable phrases from `#list_all_verification_phrases` and enroll them.
+```ruby
+  verification.create_enrollment("49a46324-fc4b-4387-aa06-090cfbf0214f", '/path/to/audio/make_him_an_offer.wav')
+  # =>
+  #   {
+  #     "enrollmentStatus" => "Enrolling",
+  #     "enrollmentsCount" => 1,
+  #     "remainingEnrollments" => 2,
+  #     "phrase" => "i am going to make him an offer he cannot refuse"
+  #   }
+```
+
+#### delete_profile(profile_id)
+Same as Identification API
+
+#### get_all_profiles
+Same as Identification API
+
+#### get_profile(profile_id)
+Same as Identification API
+
+#### reset_all_enrollments_for_profile(profile_id)
+Same as Identification API
+
+#### verify_speaker(profile_id, audio_file_path)
+User (profile) would have had to enroll with 3 of the accepted phrases (#list_all_verification_phrases).
+Once the phrases have been accepted, a recording of one of the accepted phrases can be checked against an *enrolled* profile.
+```ruby
+  verification.verify_speaker("86935587-b631-4cc7-a59t-8e580d71522g", "/path/to/audio/offer_converted.wav")
+  # =>
+  #   {
+  #    "result" => "Accept", 
+  #    "confidence" => "High", 
+  #    "phrase" => "i am going to make him an offer he cannot refuse"
+  #   }
+```

data/lib/voice_id.rb

@@ -0,0 +1,5 @@
+require_relative 'voice_id/request_helpers'
+require_relative 'voice_id/utils'
+require_relative 'voice_id/base'
+require_relative 'voice_id/identification'
+require_relative 'voice_id/verification'

data/lib/voice_id/base.rb

@@ -0,0 +1,63 @@
+module VoiceId
+  class Base
+    include RequestHelpers
+    include Utils
+
+    attr_accessor :api_base_url, :api_key, :api_version, :headers, :use_ssl
+    def initialize(api_key)
+      @api_version  = "v1.0"
+      @api_key      = api_key
+      @use_ssl      = true
+      @api_base_url = "https://api.projectoxford.ai/spid/#{@api_version}"
+      @headers      = { "Ocp-Apim-Subscription-Key" => api_key }
+    end
+
+    def create_profile(path)
+      _method   = :Post
+      _path     = path
+      _headers  = { "Content-Type" => "application/json" }
+      _body     = { :json => { :locale   => "en-us" } }
+      _response = send_request(_path, _method, _headers, _body)
+      
+      _response.code == 200 ? _response.parse : parse_error_response(_response)
+    end
+
+    # No MIME returned from API (can't parse so we return 'true')
+    def delete_profile(path)
+      _method   = :Delete
+      _path     = path
+      _headers  = { "Content-Type" => "application/json" }
+      _response = send_request(_path, _method, _headers, nil)
+
+      _response.code == 200 ? true : parse_error_response(_response)
+    end
+
+    def get_all_profiles(path)
+      _method   = :Get
+      _path     = path
+      _headers  = { "Content-Type" => "application/json" }
+      _response = send_request(_path, _method, _headers, nil)
+
+      _response.code == 200 ? _response.parse : parse_error_response(_response)
+    end
+
+    def get_profile(path)
+      _method   = :Get
+      _path     = path
+      _headers  = { "Content-Type" => "application/json" }
+      _response = send_request(_path, _method, _headers, nil)
+
+      _response.code == 200 ? _response.parse : parse_error_response(_response)
+    end
+
+    # No MIME returned from API (can't parse so we return 'true')
+    def reset_all_enrollments_for_profile(path)
+      _method   = :Post
+      _path     = path
+      _headers  = { "Content-Type" => "application/json" }
+      _response = send_request(_path, _method, _headers, nil)
+
+      _response.code == 200 ? true : parse_error_response(_response)
+    end
+  end
+end

data/lib/voice_id/identification.rb

@@ -0,0 +1,263 @@
+module VoiceId
+  class Identification < VoiceId::Base
+    class ProfileIdsMissingError < StandardError; end
+
+    # params
+    #   operationId
+    #     a valid url provided by calling #create_enrollment
+    #     an operation's status is only available for 24 hours after creating enrollment
+    #
+    # Microsoft API response
+    # 200 Response
+    #   {
+    #     "status"=>"succeeded", 
+    #     "createdDateTime"=>"2016-09-20T01:51:39.134487Z", 
+    #     "lastActionDateTime"=>"2016-09-20T01:51:41.4183611Z", 
+    #     "processingResult"=>{
+    #       "enrollmentStatus"=>"Enrolled", 
+    #       "remainingEnrollmentSpeechTime"=>0.0, 
+    #       "speechTime"=>7.93, # useful speech duration
+    #       "enrollmentSpeechTime"=>31.72
+    #      }
+    #   }
+    # 
+    # 404 Response
+    #   {
+    #     "error":{
+    #       "code" : "NotFound",
+    #       "message" : "No operation id found", 
+    #     }
+    #   }
+    #
+    # returns
+    #   success
+    #     operation status { Hash }
+    #   error
+    #     false
+    def get_operation_status(operationId)
+      _method   = :Get
+      _path     = "/operations/#{operationId}"
+      _headers  = { "Content-Type" => "application/json" }
+      _response = send_request(_path, _method, _headers, nil)
+
+      _response.code == 200 ? _response.parse : parse_error_response(_response)
+    end
+
+    # params
+    #   profileIds - required
+    #     a valid list of comma-separated values
+    #   shortAudio
+    #     set min audio length requirement to 1 sec 
+    #     (still have to provide 30 secs(multiple enrollments))
+    #   audio_file_path
+    #     string representing location of wav file in system
+    #
+    # Microsoft API response
+    # 202 Response
+    #   operation url (can be checked by calling get_operation_status(operationId))
+    #   (ex: "https://api.projectoxford.ai/spid/v1.0/operations/995a8745-0098-4c12-9889-bad14859y7a4")
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     operation url { String }
+    #   fail
+    #     false
+    def identify_speaker(profileIds, shortAudio, audio_file_path)
+      if !profileIds.is_a?(Array) || profileIds.empty?
+        raise ProfileIdsMissingError, "an array of profile ids is required"
+      end
+
+      _identificationProfileIds = profileIds.join(",")
+
+      _method   = :Post
+      _path     = "/identify?identificationProfileIds=#{_identificationProfileIds}&shortAudio=#{shortAudio}"
+      _headers  = { } 
+      _body     = create_body_for_enrollment(audio_file_path)
+      _response = send_request(_path, _method, _headers, _body)
+
+      _response.code == 202 ? _response.headers["Operation-Location"] : parse_error_response(_response)
+    end
+
+    # Microsoft API response
+    # 200 Response 
+    # {
+    #   "identificationProfileId": "49a36324-fc4b-4387-aa06-090cfbf0064f",
+    # }
+    #
+    # 500 Response
+    # {
+    #   "error":{
+    #     "code" : "InternalServerError",
+    #     "message" : "SpeakerInvalid",
+    #   }
+    # }
+    #
+    # returns
+    #   success
+    #     new profileId { Hash }
+    #   fail
+    #     false (indicating new profile was not created)
+    def create_profile
+      super("/identificationProfiles")
+    end
+
+    # params
+    #   profileId - required
+    #     a valid id { String }
+    #
+    # Microsoft API response
+    # 200 Response
+    # "" (empty string)
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     true
+    #   fail
+    #     false (indicating delete of id failed)
+    def delete_profile(profileId)
+      super("/identificationProfiles/#{profileId}")
+    end
+
+    # Microsoft API response
+    # 200 Response
+    #   [
+    #     {
+    #       "identificationProfileId" : "111f427c-3791-468f-b709-fcef7660fff9",
+    #       "locale" : "en-US",
+    #       "enrollmentSpeechTime", 0.0
+    #       "remainingEnrollmentSpeechTime" : 0.0,
+    #       "createdDateTime" : "2015-04-23T18:25:43.511Z",
+    #       "lastActionDateTime" : "2015-04-23T18:25:43.511Z",
+    #       "enrollmentStatus" : "Enrolled" //[Enrolled | Enrolling | Training]
+    #     }, 
+    #   …]
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     A list of all the profiles { Array }
+    #   fail
+    #     false (indicating delete of id failed)
+    def get_all_profiles
+      super('/identificationProfiles')
+    end
+
+    # params
+    #   profileId
+    #     a valid profileId { String }
+    #
+    # Microsoft API response
+    # 200 Response
+    #   {
+    #     "identificationProfileId" : "111f427c-3791-468f-b709-fcef7660fff9",
+    #     "locale" : "en-US",
+    #     "enrollmentSpeechTime", 0.0
+    #     "remainingEnrollmentSpeechTime" : 0.0,
+    #     "createdDateTime" : "2015-04-23T18:25:43.511Z",
+    #     "lastActionDateTime" : "2015-04-23T18:25:43.511Z",
+    #     "enrollmentStatus" : "Enrolled" //[Enrolled | Enrolling | Training]
+    #   }
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     a profile { Hash }
+    #   fail
+    #     false (indicating delete of id failed)
+    def get_profile(profileId)
+      super("/identificationProfiles/#{profileId}")
+    end
+
+    # params
+    #   profileId
+    #     a valid profileId { String }
+    #   shortAudio
+    #     false for default duration, true for any duration { Boolean }
+    #   audio_file_path
+    #     path to the audio file { String }
+    #     audio requirments => Wav, PCM, 16k rate, 16 bit sample rate, mono
+    #
+    # Microsoft API response
+    # 202 Response
+    #   url to check the enrollment status
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     a url { String }
+    #   fail
+    #     false
+    def create_enrollment(profileId, shortAudio, audio_file_path)
+      _method   = :Post
+      _path     = "/identificationProfiles/#{profileId}/enroll"
+      _headers  = { } 
+      _body     = create_body_for_enrollment(audio_file_path)
+      _response = send_request(_path, _method, _headers, _body)
+
+      _response.code == 202 ? _response.headers["Operation-Location"] : parse_error_response(_response)
+    end
+
+    # params
+    #   profileId - required
+    #     a valid id { String }
+    #
+    # Microsoft API response
+    # 200 Response
+    # "" (empty string)
+    # 
+    # 500 Response
+    #    {
+    #      "error": {
+    #        "code" : "InternalServerError",
+    #        "message" : "SpeakerInvalid", 
+    #      }
+    #   }
+    #
+    # returns
+    #   success
+    #     true
+    #   fail
+    #     false (indicating delete of enrollments failed)
+    def reset_all_enrollments_for_profile(profileId)
+      super("/identificationProfiles/#{profileId}/reset")
+    end
+    
+  end
+end