transcribeme 1.0.0.beta → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23b3a093592b85656762ec0032b8f3fa97ec6207
-  data.tar.gz: aa03e89273d1f655371f8b0010b7593aefead40a
+  metadata.gz: 43e368c48c116a708dbccda72fcd53bbd7806b6d
+  data.tar.gz: 6e0539e5685c05334515b4eafae526d848aee3d8
 SHA512:
-  metadata.gz: f48989a92f98d16306b82277a31922184a86b38bd77524a119d5eff4af61b2fb0c0d43fb1a828043432241515557e3acd9598f40adf8c5877de154d94ac13354
-  data.tar.gz: 2c8dd584070feff6d3bccc6d9abf09a92d205ca7eb19bf26fe72cfc0feabdf9a66c4facf7557b4eb6de6345bcee8cc33fdccfc5da41f0e0d0e66b8e854483a26
+  metadata.gz: 8a894f41121bf13ebf66662820d98348f038fdc1c49da7eaa81abac75360dd8a77c2fb74191cf703ef51577382724e66dafc5041d8c50034f32328aca110eee7
+  data.tar.gz: 61df26e41e3f1307b1cfb8a5d117416b525c7c33ee14c35ba7f27599fe37b481dfa0aa328e514544a84d8771415d5803797f686f706950922e03f47176585a78

data/.gitignore

@@ -18,4 +18,5 @@ test/tmp
 test/version_tmp
 tmp
 .ruby-gemset
-.ruby-version
+.ruby-version
+pkg/

data/README.md

@@ -10,11 +10,7 @@
 
 This gem is a Ruby wrapper for the TranscribeMe SOAP API, built on Savon, and includes some extra dangly bits for uploading to Windows Azure Blob storage.
 
-The DSL may change before 1.0.0 stable is released. 
-
-Changes from prior 1.0.0 include bringing the Ruby method names in line with the actual SOAP action names.
-
-This gem wants to make it easy for you. If you call the 'sign_in' method before initializing a session then we all know you meant to. We'll jump right in there and initialize it for you.
+This gem wants to make it easy for you. It tries, at least. If you call the 'sign_in' method before initializing a session then we all know you meant to. We'll jump right in there and initialize it for you.
 
 ## Prerequisites
 
@@ -36,100 +32,7 @@ Or install it yourself as:
 
 ## Usage
 
-To get a file transcribed with this gem, this is the workflow:
-
-- Sign in as a Customer
-- Upload a file
-- Submit for transcription (possibly with a Promocode)
-
-
-#### Signing in
-
-To create a new instance of the API client
-
-    client = TranscribeMe::API::Client.new
-
-API Sessions have a lifetime of 1 hour. When we sign in as a user an API session will be created if it is either no longer valid or not yet initialized.
-
-    client.sign_in 'example@transcribeme.com', 'example'
-
-GUIDs are prolific. Your session id is a GUID, and will be available in `client.session_id` but the result of signing in will return your Customer ID. Don't worry, you won't need this.
-
-#### Getting a list of recordings
-
-To get your recordings, call the `get_recordings` method:
-
-    recordings = client.get_recordings
-
-This will return an array of hashes. These hashes have the following keys: `:date_created`, `:duration`, `:id`, `:name` and `:status`.
-
-TODO: Status is currently slightly cryptic, and this will improve.
-
-    "10" # => Ready for transcription
-    "40" # => In Progress
-    "50" # => Complete
-
-using `Array#select` you can filter for recordings that are in progress, complete or ready for transcription. This will be refactored post 1.0.0.
-
-Array#select examples:
-
-    completed   = recordings.select {|x| x[:status] == "50"}
-    in_progress = recordings.select {|x| x[:status] == "40"}
-    ready       = recordings.select {|x| x[:status] == "10"}
-
-#### Uploading recordings
-
-###### Prerequisites
-
-NOTE: This piece of functionality (and actually only this) relies on FFMPEG and the `streamio-ffmpeg` Ruby gem, unless you explicitly state the duration of the audio in an options hash.
-
-On Ubuntu:
-
-    sudo apt-get install ffmpeg
-
-(or your Linux package manager to install the ffmpeg package)
-
-On Mac:
-
-Get [Homebrew](http://brew.sh/) and then
-
-    brew install ffmpeg
-
-
-Not yet tested on Windows environments. Feel free to send feedback / advice on an FFMPEG alternative.
-
-
-RubyMotion - this gem uses synchronous connections, and other stuff making it inappropriate. A RubyMotion-specific gem is in the works.
-
-###### Actually uploading files
-
-    client.upload 'my_cool_file.mp3'
-
-That's pretty easy, right?
-
-Or you can also include a second argument, to overwrite the defaults.
-
-      # options   - a Hash with these keys:
-      #             :multiple_speakers  - Boolean (default is true)
-      #             :duration           - Float
-      #             :description        - String
-
-    client.upload 'my_cool_file.mp3', { duration: 12345.12, multiple_speakers: false, description: "Yo!" }
-
-This can take some time, as it first uses [Excon](http://excon.io/) to upload to Windows Azure Blob Storage, using the URL asked provided by the API. Once the upload to Windows Azure completes, it sends a SOAP request to the API to confirm the file name and details. The recording is then in the initial state - Status 10, Ready for Transcription.
-
-The return value is the response hash, which includes the Recording ID. This Recording ID is a GUID, and you may want to hold on to it. It will be available in the list of recordings.
-
-#### Submitting recordings for transcription
-
-If you have used the [web interface](https://portal.transcribeme.com) to set up payment you can use the transcribe_recording method like so:
-
-    client.transcribe_recording '5e38e162-3e05-4f4d-82c1-010a34891fd8'
-
-or if you have a promo code:
-
-    client.transcribe_recording_using_promocode '5e38e162-3e05-4f4d-82c1-010a34891fd8', 'MyPromoCodeRules'
-
+See USAGE.md
 
 ## Documentation
 
@@ -141,14 +44,13 @@ The documentation can be [browsed online](http://rubydoc.info/github/tuttinator/
 
 Version 1.0.0 stable
 
-- [ ] Write specs
+- [ ] Write specs (WIP)
 - [x] Set up Travis-CI and document supported Ruby versions
 - [x] Investigate Windows Azure Blob storage file upload
 - [x] Include Excon for Windows Azure Blob storage
 - [x] Base64 decrypt transcription results
 - [ ] Document SOAP calls and error messages
 - [ ] Complete YARD documentation
-- [ ] Include option (default)
 - [ ] Validations for GUIDs 
 - [ ] Exceptions for error handling (about 50%)
 - [ ] Modelling Recording objects, particularly better describing recording status

data/USAGE.md

@@ -1,27 +1,103 @@
-### Design decisions
+# Usage
 
-Interact directly with API calls like this:
+To get a file transcribed with this gem, this is the workflow:
+
+- Sign in as a Customer
+- Upload a file
+- Submit for transcription (possibly with a Promocode)
+
+
+#### Signing in
+
+To create a new instance of the API client
 
     client = TranscribeMe::API::Client.new
 
-    client.login_as_customer({username: "customer@transcribeme.com", password: PASSWORD})
-    client.recordings # => [List of recording instances...]
+API Sessions have a lifetime of 1 hour. When we sign in as a user an API session will be created if it is either no longer valid or not yet initialized.
+
+    client.sign_in 'example@transcribeme.com', 'example'
+
+GUIDs are prolific. Your session id is a GUID, and will be available in `client.session_id` but the result of signing in will return your Customer ID. Don't worry, you won't need this.
+
+#### Getting a list of recordings
+
+To get your recordings, call the `get_recordings` method:
+
+    recordings = client.get_recordings
+
+This will return a object which holds an array of recording instances. These objects have the following keys: `:date_created`, `:duration`, `:id`, `:name`, `:status` and `:state`.
+
+To view all the items in the array, use the `.list` or `.all` class methods.
+
+The Recording class delegates methods to the array of recordings, but also includes convenience methods:
+
+    recordings.completed
+    recordings.in_progress
+    recordings.processing_audio
+    recordings.ready_for_transcription
+
+Anything you might expect to be able to do on an array is possible thanks to the magic of Ruby's `method_missing`:
+
+    recordings.each do |recording|
+      puts recording[:name]
+    end
+
+Instances of the recording class have appropriate type-casting, partially due to the magic Savon gives us (type casting a date string to a DateTime object), and this class cleans up the odd String into a float or integer as appropriate.
+
+Please note, that durations are floats in seconds.
+
+#### Uploading recordings
+
+###### Prerequisites
+
+NOTE: This piece of functionality (and actually only this) relies on FFMPEG and the `streamio-ffmpeg` Ruby gem, unless you explicitly state the duration of the audio in an options hash.
+
+On Ubuntu:
+
+    sudo apt-get install ffmpeg
+
+(or your Linux package manager to install the ffmpeg package)
+
+On Mac:
+
+Get [Homebrew](http://brew.sh/) and then
+
+    brew install ffmpeg
+
+
+Not yet tested on Windows environments. Feel free to send feedback / advice on an FFMPEG alternative.
+
+
+RubyMotion - this gem uses synchronous connections, and other stuff making it inappropriate. A RubyMotion-specific gem is in the works.
+
+###### Actually uploading files
+
+    client.upload 'my_cool_file.mp3'
+
+That's pretty easy, right?
+
+Or you can also include a second argument, to overwrite the defaults.
+
+      # options   - a Hash with these keys:
+      #             :multiple_speakers  - Boolean (default is true)
+      #             :duration           - Float
+      #             :description        - String
+
+
+An example of using these options looks like this:
+
+    client.upload 'my_cool_file.mp3', { duration: 12345.12, multiple_speakers: false, description: "Yo!" }
+
+This can take some time, as it first uses [Excon](http://excon.io/) to upload to Windows Azure Blob Storage, using the URL asked provided by the API. Once the upload to Windows Azure completes, it sends a SOAP request to the API to confirm the file name and details. The recording is then in the initial state - Status 10, Ready for Transcription.
 
-    client.get_recording(recording_id) # => <Recording:0x007fc69e49f0b8>
+The return value is the response hash, which includes the Recording ID. This Recording ID is a GUID, and you may want to hold on to it. It will be available in the list of recordings.
 
-    client.submit_recording(recording_id) # => true or false
+#### Submitting recordings for transcription
 
-Or interact through a customer object
+If you have used the [web interface](https://portal.transcribeme.com) to set up payment you can use the transcribe_recording method like so:
 
-    customer = Customer.new(username: "customer@transcribeme.com", password: PASSWORD)
-  
-  or
-    customer = {username: "customer@transcribeme.com", password: PASSWORD}
-  
-  or
-    customer = Struct.new(:username, :password)
-  
+    client.transcribe_recording '5e38e162-3e05-4f4d-82c1-010a34891fd8'
 
-  client.login_as_customer(customer) 
-  either a hash, or a duck-typed object which either responds to [:username] and [:password] or #username and #password
+or if you have a promo code:
 
+    client.transcribe_recording_using_promocode '5e38e162-3e05-4f4d-82c1-010a34891fd8', 'MyPromoCodeRules'

data/lib/transcribeme.rb

@@ -2,4 +2,5 @@ require 'savon'
 require 'streamio-ffmpeg'
 require 'excon'
 require 'transcribeme/version'
+require 'transcribeme/api/recording'
 require 'transcribeme/api/client'

data/lib/transcribeme/api/client.rb

@@ -11,6 +11,8 @@ module TranscribeMe
       attr_reader :session_expiry_time
       # Public: Returns the underlining Savon object
       attr_reader :savon
+      # Public: Returns the last list of recordings
+      attr_reader :recordings
 
       WSDL = 'http://transcribeme-api.cloudapp.net/PortalAPI.svc?wsdl=wsdl0'
       ENDPOINT = 'http://transcribeme-api.cloudapp.net/PortalAPI.svc'
@@ -67,14 +69,15 @@ module TranscribeMe
       #
       # requires the user to be logged in
       #
-      # Returns an Array of Hashes of with the properties of recording objects
+      # Returns an Array of recording objects
       def get_recordings
         # raise 'Login first!' unless @customer_login_id
 
         response = @savon.call  :get_customer_recordings, 
                                 message: {  'wsdl:sessionID' => session_id }
 
-        @recordings = response.body[:get_customer_recordings_response][:get_customer_recordings_result][:recording_info]                                
+        # Returns an array of instances of the Recording class
+        @recordings = Recording.new_from_soap response.body[:get_customer_recordings_response][:get_customer_recordings_result][:recording_info]
       end
 
       # Public: Calls the 'GetUploadUrl' SOAP Action
@@ -168,7 +171,7 @@ module TranscribeMe
                                           'wsdl:recordingId' => recording_id,
                                           'wsdl:promoCode'   => promocode }
 
-        response.body[:transcribe_recording_using_promocode_response][:transcribe_recording_using_promocode_result]
+        response.body[:transcribe_using_promo_code_response][:transcribe_using_promo_code_result]
       end
 
       # Public: Calls the 'GetRecordingInfo' SOAP Action
@@ -230,6 +233,7 @@ module TranscribeMe
         @session_expiry_time > Time.now if @session_expiry_time
       end
 
+
     end
 
   end

data/lib/transcribeme/api/recording.rb

@@ -0,0 +1,197 @@
+# TranscribeMe
+module TranscribeMe
+  # API module
+  module API
+    # representation of recording objects
+    class Recording
+
+      # Define attributes
+      ATTRIBUTES = [:date_created, :duration, :id, :name, :status, :state]
+
+      # Recording attributes
+      ATTRIBUTES.each do |attr|
+        attr_reader attr
+      end
+
+      # Define status codes
+      STATUS_CODES = { 
+        0  => "New",
+        4  => "File Queued for Upload",
+        6  => "Error during Upload",
+        7  => "Empty File. Nothing to upload",
+        8  => "Upload in Progress",
+        10 => "Ready for Transcription",
+        20 => "Awaiting Payment",
+        30 => "Queued",
+        33 => "TempBeforeHTK",
+        35 => "Processing Audio",
+        40 => "In Progress",
+        50 => "Completed",
+        90 => "Deleted" }
+
+
+      # Public: Initializes the Recording class
+      #
+      # recording - Hash with attributes from SOAP response
+      #
+      def initialize(recording)
+        recording.each do |key, value|
+          if ATTRIBUTES.member? key.to_sym
+            self.send (key.to_s + "="), value
+          end
+        end
+      end
+
+      # Public: Hash-like access to the attributes
+      #
+      # key - String or Symbol
+      #
+      # Returns the result of that method call
+      def [](key)
+        self.send key.to_sym
+      end
+
+      def keys
+        ATTRIBUTES
+      end
+
+      private
+
+      # Private: Iterate through all attributes and define setter
+      #  methods on them
+      ATTRIBUTES.each do |attr|
+        case attr
+        when :status
+          # Private: Sets the state as well as the status according
+          #   to the status code
+          #
+          # value - string
+          #
+          # Returns the status code as an Integer
+          define_method :status= do |value|
+            @state = STATUS_CODES[value.to_i]
+            @status = value.to_i
+          end
+        when :duration
+          # Private: Sets the duration as a float
+          #
+          # value - string
+          #
+          # Returns the duration as an Float
+          define_method :duration= do |value|
+            @duration = value.to_f
+          end
+        else
+          # Private: Setter methods for the date_created, id and 
+          #   name attributes
+          #
+          # value - object
+          #
+          # Returns the Object after assigning to an instance variable
+          define_method :"#{attr}=" do |value|
+            instance_variable_set :"@#{attr}", value
+          end
+        end
+      end
+
+      # Class Methods
+      class << self
+
+        # Public: recording instances as a class instance
+        #   variable
+        #
+        # Returns the Array of recording instances
+        def all
+          # Assign to an empty array if nil
+          @@list ||= []
+        end
+
+        # Alias the .list method to .all
+        alias_method :list, :all
+        # Alias the .to_a method to .all
+        alias_method :to_a, :all
+
+
+        # Public: Returns an array of recording instances
+        #
+        # recordings - an Array of Hashes returned from a SOAP call
+        #
+        # Returns an Array of Recording instances
+        def new_from_soap(recordings)
+          # Reset the list array to be blank
+          @@list = []
+          recordings.map do |recording|
+            @@list << self.new(recording)
+          end
+          self
+        end
+
+        # Public: Display information about the number of recordings available
+        #
+        # Returns a String
+        def inspect
+          "TranscribeMe::API::Recordings count=#{list.count} list=[...] "
+        end
+
+        # Alias .to_s to .inspect for convenience
+        alias_method :to_s, :inspect
+
+
+        # Public: Gets the list of completed recordings
+        #
+        # Returns an Array with only the recordings of status 50
+        def completed
+          list.select {|l| l[:status] == 50 }
+        end
+
+        # Public: Gets the list of in progress recordings
+        #
+        # Returns an Array with only the recordings of status 40
+        def in_progress
+          list.select {|l| l[:state] == 40 }
+        end
+
+        # Public: Gets the list of recordings currently processing audio
+        #
+        # Returns an Array with only the recordings of status 35
+        def processing_audio
+          list.select {|l| l[:state] == 35 }
+        end
+
+        # Public: Gets the list of recordings currently ready for transcription
+        #
+        # Returns an Array with only the recordings of status 10
+        def ready_for_transcription
+          list.select {|l| l[:state] == 10 }
+        end
+
+        # Alias :ready_for_transcription to :ready for convenience
+        alias_method :ready, :ready_for_transcription
+
+        # Public: Delegate methods we don't understand to the array
+        #
+        # method - a String or Symbol
+        # *args  - optional variable arguments
+        # &block - optional block
+        #
+        # Example:
+        #
+        #    Recording.each do |recording|
+        #      puts recording[:name]
+        #    end
+        #
+        # Returns the result of the delegated method call or
+        #  raises a runtime error if the method isn't findable
+        def method_missing(method, *args, &block)
+          if list.respond_to? method.to_sym
+            list.send(method.to_sym, *args, &block)
+          else
+            super
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/transcribeme/version.rb

@@ -1,4 +1,4 @@
 # TranscribeMe namespace
 module TranscribeMe
-  VERSION = '1.0.0.beta'
+  VERSION = '1.0.0'
 end

data/spec/lib/api/client_spec.rb

@@ -101,7 +101,7 @@ describe TranscribeMe::API::Client do
     end
 
     it 'returns an array of recordings' do
-      expect(@recordings.class.to_s).to eq "Array"
+      expect(@recordings.list.class.to_s).to eq "Array"
     end
 
     describe 'recordings' do
@@ -111,7 +111,7 @@ describe TranscribeMe::API::Client do
       end
 
       it 'has properties' do
-        expect(@recording.keys).to eq [:date_created, :duration, :id, :name, :status]
+        expect(@recording.keys).to eq [:date_created, :duration, :id, :name, :status, :state]
       end
 
     end

data/spec/support/sample_errors.yaml

@@ -0,0 +1,3 @@
+errors:
+  expired_session: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><SignInResponse xmlns="http://TranscribeMe.API.Web"><SignInResult>00000000-0000-0000-0000-000000000000</SignInResult><errorCode>100</errorCode><errorMessage>Requested session has been removed or expired.</errorMessage></SignInResponse></s:Body></s:Envelope>
+  invalid_credentials: <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"><s:Body><SignInResponse xmlns="http://TranscribeMe.API.Web"><SignInResult>00000000-0000-0000-0000-000000000000</SignInResult><errorCode>204</errorCode><errorMessage>Provided credentials are invalid. Please check your login and password and try again.</errorMessage></SignInResponse></s:Body></s:Envelope>

data/transcribeme.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'savon', '~> 2.2'
+  spec.add_runtime_dependency 'savon', '~> 2.3.0'
   spec.add_runtime_dependency 'excon', '~> 0.25.3'
   spec.add_runtime_dependency 'streamio-ffmpeg', '~> 1.0.0'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transcribeme
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta
+  version: 1.0.0
 platform: ruby
 authors:
 - Tuttinator
@@ -31,7 +31,7 @@ cert_chain:
   /qqRTsuOOmPoaNtB4XnGMXyHOzOhAvurliPCtBFlkWAH0RvDt29O9ZcwRhInvr83
   S4meqecZ62/XH48iGccggmMPiTi8zQ==
   -----END CERTIFICATE-----
-date: 2013-09-03 00:00:00.000000000 Z
+date: 2013-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: savon
@@ -39,14 +39,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: 2.3.0
 - !ruby/object:Gem::Dependency
   name: excon
   requirement: !ruby/object:Gem::Requirement
@@ -180,13 +180,8 @@ files:
 - USAGE.md
 - lib/transcribeme.rb
 - lib/transcribeme/api/client.rb
+- lib/transcribeme/api/recording.rb
 - lib/transcribeme/version.rb
-- pkg/transcribeme-0.0.1.gem
-- pkg/transcribeme-0.0.2.beta.gem
-- pkg/transcribeme-0.0.2.pre.gem
-- pkg/transcribeme-0.0.3.alpha1.gem
-- pkg/transcribeme-0.0.4.beta1.gem
-- pkg/transcribeme-0.0.5.beta.gem
 - spec/lib/api/client_spec.rb
 - spec/spec_helper.rb
 - spec/support/audio/yes-we-can-speech.mp3
@@ -196,6 +191,7 @@ files:
 - spec/support/cassettes/successful_sign_in_after_initialize_call.yml
 - spec/support/cassettes/unsuccessful_sign_in.yml
 - spec/support/cassettes/upload_url.yml
+- spec/support/sample_errors.yaml
 - transcribeme.gemspec
 homepage: http://tuttinator.github.io/transcribeme/
 licenses:
@@ -212,9 +208,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.0.3
@@ -231,4 +227,5 @@ test_files:
 - spec/support/cassettes/successful_sign_in_after_initialize_call.yml
 - spec/support/cassettes/unsuccessful_sign_in.yml
 - spec/support/cassettes/upload_url.yml
+- spec/support/sample_errors.yaml
 has_rdoc: