animoto 0.0.0.alpha9 → 0.1.0.beta0

data/README.md

@@ -31,6 +31,19 @@ This document does not cover the details of the Animoto API itself. For such inf
 <a name="getting_started_using_the_ruby_client"></a>
 ## Getting Started using the Ruby Client
 
+### Installation
+
+You can install the Animoto API Ruby Client either through [RubyGems](http://rubygems.org):
+
+    gem install animoto -v 0.1.0.alpha0 --pre
+
+Or by cloning [the repository](http://github.com/animoto/animoto_api_client_ruby) on [GitHub](http://github.com/) and building it from source:
+
+    git clone git://github.com/animoto/animoto_api_client_ruby.git
+    cd animoto_api_client_ruby
+    gem build animoto.gemspec
+    gem install animoto-0.1.0.alpha0.gem
+
 ### Prerequisites
 
 #### Readers of this document should be familiar with...
@@ -87,7 +100,7 @@ client and using HTTP callbacks for status updates.
     # create a directing and rendering manifest with the video title and 
     # producer.  Also include rendering parameters like resolution, framerate,
     # and format.
-    manifest = DirectingAndRenderingManifest.new(
+    manifest = Manifests::DirectingAndRendering.new(
       :title => "Amazing Title!", 
       :producer => "Fishy Joe", 
       :resolution => "720p", 
@@ -96,13 +109,13 @@ client and using HTTP callbacks for status updates.
     )
     
     # Add some images, text, and footage to our manifest.
-    manifest << Image.new("http://website.com/picture.png")
-    manifest << Image.new("http://website.com/hooray.png", :spotlit => true)
-    manifest << TitleCard.new("Woohoo!", "Hooray for everything!")
-    manifest << Footage.new("http://website.com/movie.mp4", :duration => 3.5)
+    manifest << Assets::Image.new("http://website.com/picture.png")
+    manifest << Assets::Image.new("http://website.com/hooray.png", :spotlit => true)
+    manifest << Assets::TitleCard.new("Woohoo!", "Hooray for everything!")
+    manifest << Assets::Footage.new("http://website.com/movie.mp4", :duration => 3.5)
     
     # Setup the soundtrack.
-    manifest << Song.new("http://website.com/song.mp3", :artist => "Fishy Joe")
+    manifest << Assets::Song.new("http://website.com/song.mp3", :artist => "Fishy Joe")
     
     # Setup to get http callbacks for status notification (see below for 
     # polling example).
@@ -128,16 +141,16 @@ status.
 
     # Create a directing manifest.  The directing manifest controls the images
     # and other visual elements that will be in our final video.
-    manifest = DirectingManifest.new(:title => "Amazing Title!")
+    manifest = Manifests::Directing.new(:title => "Amazing Title!")
     
     # Add some images, text, and footage to our manifest.
-    manifest << Image.new("http://website.com/picture.png")
-    manifest << Image.new("http://website.com/hooray.png", :spotlit => true)
-    manifest << TitleCard.new("Woohoo!", "Hooray for everything!")
-    manifest << Footage.new("http://website.com/movie.mp4", :duration => 3.5)
+    manifest << Assets::Image.new("http://website.com/picture.png")
+    manifest << Assets::Image.new("http://website.com/hooray.png", :spotlit => true)
+    manifest << Assets::TitleCard.new("Woohoo!", "Hooray for everything!")
+    manifest << Assets::Footage.new("http://website.com/movie.mp4", :duration => 3.5)
     
     # Setup the soundtrack.
-    manifest << Song.new("http://website.com/song.mp3")
+    manifest << Assets::Song.new("http://website.com/song.mp3")
 
     # Request a new directing job by sending the API our directing manifest.
     directing_job = client.direct!(manifest)
@@ -154,7 +167,7 @@ status.
     
       # Now it's time to render the storyboard into a video.  First we create
       # a rendering manifest.
-    	manifest = RenderingManifest.new(storyboard, :resolution => "720p", :framerate => 24, :format => 'h264')
+    	manifest = Manifests::Rendering.new(storyboard, :resolution => "720p", :framerate => 24, :format => 'h264')
     	
     	# Send the manifest to the API.
     	rendering_job = client.render!(manifest)

data/integration/test.rb

@@ -33,7 +33,7 @@ raise "Example code not found in README (expected at xpath '#{example_code_path}
 code = code_node.text
 
 puts "Replacing example credentials with valid ones"
-code.sub!(/Client\.new\(.+\)/, %Q{Client.new("#{credentials[:key]}","#{credentials[:secret]}")})
+code.sub!(/Client\.new\(.+\)/, %Q{Client.new("#{credentials[:key]}","#{credentials[:secret]}",:endpoint => "#{credentials[:endpoint]}")})
 
 puts "Replacing example assets with valid ones"
 code.gsub!(/Image\.new\(.+\)/) { %Q{Image.new("#{assets[:images].shift}")} }
@@ -46,5 +46,4 @@ puts "Executing example"
 eval code
 
 puts
-puts "If you're seeing this, things should have worked fine!"
-puts "Enjoy your video at #{video.download_url}"
+puts "If you're seeing this, things should have worked fine!"

data/lib/animoto/assets/base.rb

@@ -0,0 +1,29 @@
+module Animoto
+  module Assets
+
+    # @abstract
+    class Base
+      
+      # The URL of this asset.
+      # @return [String]
+      attr_accessor :source
+      
+      # Creates a new asset.
+      #
+      # @param [String] source the URL of this asset
+      # @return [Assets::Base] the asset
+      def initialize source, options = {}
+        @source = source
+      end
+    
+      # Returns a representation of this asset as a Hash. Used mainly for generating
+      # manifests.
+      #
+      # @return [Hash<String,Object>] this asset as a Hash
+      def to_hash
+        { 'source_url' => @source }
+      end
+
+    end
+  end
+end

data/lib/animoto/assets/footage.rb

@@ -0,0 +1,34 @@
+module Animoto
+  module Assets
+    class Footage < Animoto::Assets::Base
+      include Support::Visual
+      include Support::Coverable
+      
+      # Whether or not to mix the audio of this footage with the video's soundtrack.
+      # @return [Boolean]
+      attr_accessor :audio_mix
+      
+      # The time in seconds of where to start extracting a clip from this footage to
+      # add to the video.
+      # @return [Float]
+      attr_accessor :start_time
+      
+      # The duration in seconds of how long this footage should run in the video.
+      # @return [Float]
+      attr_accessor :duration
+    
+      # Returns a representation of this Footage as a Hash.
+      #
+      # @return [Hash<String,Object>] this asset as a Hash
+      # @see Animoto::Support::Visual#to_hash
+      # @see Animoto::Assets::Base#to_hash
+      def to_hash
+        hash = super
+        hash['audio_mix'] = 'MIX' if audio_mix
+        hash['start_time'] = start_time if start_time
+        hash['duration'] = duration if duration
+        hash 
+      end
+    end
+  end
+end

data/lib/animoto/assets/image.rb

@@ -0,0 +1,25 @@
+module Animoto
+  module Assets
+    class Image < Animoto::Assets::Base
+      include Support::Visual
+      include Support::Coverable
+
+      # The EXIF rotation value for how this image should be rotated in the video.
+      # @return [Integer]
+      attr_accessor :rotation
+    
+      # Returns a representation of this Image as a Hash.
+      #
+      # @return [Hash<String,Object>] this asset as a Hash
+      # @see Animoto::Support::Visual#to_hash
+      # @see Animoto::Assets::Base#to_hash
+      def to_hash
+        hash = super
+        hash['rotation'] = rotation if rotation
+        hash['spotlit'] = spotlit? unless @spotlit.nil?
+        hash['cover'] = cover? unless @cover.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/animoto/assets/song.rb

@@ -0,0 +1,27 @@
+module Animoto
+  module Assets
+    class Song < Animoto::Assets::Base
+      
+      # The offset in seconds from the beginning denoting where to start
+      # using this song in the video.
+      # @return [Float]
+      attr_accessor :start_time
+      
+      # The duration in seconds of how long this song should play.
+      # @return [Float]
+      attr_accessor :duration
+    
+      # Returns a representation of this Song as a Hash.
+      #
+      # @return [Hash<String,Object>] this asset as a Hash
+      # @see Animoto::Assets::Base#to_hash
+      def to_hash
+        hash = super
+        hash['start_time'] = start_time if start_time
+        hash['duration'] = duration if duration
+        hash
+      end
+    
+    end
+  end
+end

data/lib/animoto/assets/title_card.rb

@@ -0,0 +1,35 @@
+module Animoto
+  module Assets
+    class TitleCard
+      include Support::Visual
+      
+      # The main text of this title card.
+      # @return [String]
+      attr_accessor :title
+      
+      # The secondary text of this title card.
+      # @return [String]
+      attr_accessor :subtitle
+    
+      # Creates a new TitleCard.
+      #
+      # @param [String] title the main text
+      # @param [String] subtitle the secondary text
+      def initialize title, subtitle = nil
+        @title, @subtitle = title, subtitle
+      end
+    
+      # Returns a representation of this TitleCard as a Hash.
+      #
+      # @return [Hash<String,Object>] this TitleCard as a Hash
+      # @see Animoto::Support::Visual#to_hash
+      def to_hash
+        hash = super
+        hash['h1'] = title
+        hash['h2'] = subtitle if subtitle
+        hash['spotlit'] = spotlit? unless @spotlit.nil?
+        hash
+      end
+    end
+  end
+end

data/lib/animoto/callbacks/base.rb

@@ -0,0 +1,45 @@
+module Animoto
+  module Callbacks
+
+    # @abstract
+    class Base
+      include Support::StandardEnvelope
+
+      # @return [String]
+      # @see Animoto::Support::StandardEnvelope::ClassMethods#payload_key
+      def self.payload_key
+        super + '_callback'
+      end
+      
+      # @return [Hash<Symbol,Object>]
+      # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
+      def self.unpack_standard_envelope body = {}
+        super.merge({ :state => body['response']['payload'][payload_key]['state'] })
+      end
+
+      # The state of the job when it completed.
+      # @return [String]
+      attr_reader :state
+      
+      # Errors for the job.
+      # @return [Array<Animoto::Error>]
+      attr_reader :errors
+      
+      # The url for this job.
+      # @return [String]
+      attr_reader :url
+
+      # Creates a new Callback.
+      #
+      # @param [String] body the request body of the HTTP callback
+      # @return [Callbacks::Base] the Callback
+      def initialize body
+        params = unpack_standard_envelope(body)
+        @state  = params[:state]
+        @errors = params[:errors].collect { |e| Animoto::Error.new(e['message']) }
+        @url    = params[:url]
+      end
+      
+    end
+  end
+end

data/lib/animoto/callbacks/directing.rb

@@ -0,0 +1,7 @@
+module Animoto
+  module Callbacks
+    class Directing < Animoto::Callbacks::Base
+      
+    end
+  end
+end

data/lib/animoto/callbacks/directing_and_rendering.rb

@@ -0,0 +1,7 @@
+module Animoto
+  module Callbacks
+    class DirectingAndRendering < Animoto::Callbacks::Base
+      
+    end
+  end
+end

data/lib/animoto/callbacks/rendering.rb

@@ -0,0 +1,7 @@
+module Animoto
+  module Callbacks
+    class Rendering < Animoto::Callbacks::Base
+      
+    end
+  end
+end

data/lib/animoto/client.rb

@@ -2,30 +2,39 @@ require 'yaml'
 require 'uri'
 require 'logger'
 
-require 'animoto/errors'
-require 'animoto/content_type'
-require 'animoto/standard_envelope'
-require 'animoto/resource'
-require 'animoto/asset'
-require 'animoto/visual'
-require 'animoto/coverable'
-require 'animoto/footage'
-require 'animoto/image'
-require 'animoto/song'
-require 'animoto/title_card'
-require 'animoto/manifest'
-require 'animoto/directing_manifest'
-require 'animoto/rendering_manifest'
-require 'animoto/directing_and_rendering_manifest'
-require 'animoto/storyboard'
-require 'animoto/video'
-require 'animoto/job'
-require 'animoto/directing_and_rendering_job'
-require 'animoto/directing_job'
-require 'animoto/rendering_job'
-require 'animoto/dynamic_class_loader'
-require 'animoto/http_engine'
-require 'animoto/response_parser'
+require 'animoto/support/content_type'
+require 'animoto/support/coverable'
+require 'animoto/support/dynamic_class_loader'
+require 'animoto/support/errors'
+require 'animoto/support/standard_envelope'
+require 'animoto/support/visual'
+
+require 'animoto/resources/base'
+require 'animoto/resources/storyboard'
+require 'animoto/resources/video'
+require 'animoto/resources/jobs/base'
+require 'animoto/resources/jobs/directing_and_rendering'
+require 'animoto/resources/jobs/directing'
+require 'animoto/resources/jobs/rendering'
+
+require 'animoto/assets/base'
+require 'animoto/assets/footage'
+require 'animoto/assets/image'
+require 'animoto/assets/song'
+require 'animoto/assets/title_card'
+
+require 'animoto/manifests/base'
+require 'animoto/manifests/directing'
+require 'animoto/manifests/directing_and_rendering'
+require 'animoto/manifests/rendering'
+
+require 'animoto/callbacks/base'
+require 'animoto/callbacks/directing'
+require 'animoto/callbacks/directing_and_rendering'
+require 'animoto/callbacks/rendering'
+
+require 'animoto/http_engines/base'
+require 'animoto/response_parsers/base'
 
 module Animoto
   class Client
@@ -33,8 +42,54 @@ module Animoto
     API_VERSION       = 1
     BASE_CONTENT_TYPE = "application/vnd.animoto"
     
-    attr_accessor :key, :secret, :endpoint, :logger
-    attr_reader :http_engine, :response_parser
+    # Your API key.
+    # @return [String]
+    attr_accessor :key
+    
+    # Your API secret.
+    # @return [String]
+    attr_accessor :secret
+    
+    # The base URL where all requests will be sent.
+    # @return [String]
+    attr_accessor :endpoint
+    
+    # A logger.
+    # @return [Logger]
+    attr_accessor :logger
+    
+    # The engine to handle HTTP requests.
+    # @return [HTTPEngines::Base]
+    # @overload http_engine
+    #   Returns the HTTP engine.
+    #   @return [HTTPEngines::Base]
+    # @overload http_engine=(engine)
+    #   Sets the HTTP engine.
+    #   
+    #   @param [HTTPEngines::Base,Symbol,Class] engine you may pass a
+    #     HTTPEngine instance to use, or the symbolic name of an adapter to use,
+    #     or a Class whose instances respond to #request and return a String of
+    #     the response body
+    #   @see Animoto::HTTPEngines::Base
+    #   @return [HTTPEngines::Base] the engine instance
+    #   @raise [ArgumentError] if given a class without the correct interface
+    attr_reader :http_engine
+    
+    # The engine to handle parsing XML or JSON responses.
+    # @return [ResponseParsers::Base]
+    # @overload response_parser
+    #   Returns the parser.
+    #   @return [ResponseParsers::Base]
+    # @overload response_parser=(parser)
+    #   Sets the parser.
+    #   
+    #   @param [ResponseParsers::Base,Symbol,Class] parser you may pass a
+    #     ResponseParser instance to use, or the symbolic name of an adapter to use,
+    #     or a Class whose instances respond to #parse, #unparse, and #format.
+    #   @see Animoto::ResponseParsers::Base
+    #   @return [ResponseParsers::Base] the parser instance
+    #   @raise [ArgumentError] if given a class without the correct interface
+    attr_reader :response_parser
     
     # Creates a new Client object which handles credentials, versioning, making requests, and
     # parsing responses.
@@ -60,18 +115,9 @@ module Animoto
       __send__ :response_parser=, options[:response_parser] || :json
     end
     
-    # Set the HTTP engine this client will use.
-    # 
-    # @param [HTTPEngine, Symbol, Class] engine you may pass a
-    #   HTTPEngine instance to use, or the symbolic name of a adapter to use,
-    #   or a Class whose instances respond to #request and return a String of
-    #   the response body
-    # @see Animoto::HTTPEngine
-    # @return [HTTPEngine] the engine instance
-    # @raise [ArgumentError] if given a class without the correct interface
     def http_engine= engine
       @http_engine = case engine
-      when Animoto::HTTPEngine
+      when Animoto::HTTPEngines::Base
         engine
       when Class
         if engine.instance_methods.include?('request')
@@ -80,21 +126,13 @@ module Animoto
           raise ArgumentError
         end
       else
-        Animoto::HTTPEngine[engine].new
+        Animoto::HTTPEngines[engine].new
       end
     end
     
-    # Set the response parser this client will use.
-    # 
-    # @param [ResponseParser, Symbol, Class] parser you may pass a
-    #   ResponseParser instance to use, or the symbolic name of a adapter to use,
-    #   or a Class whose instances respond to #parse, #unparse, and #format.
-    # @see Animoto::ResponseParser
-    # @return [ResponseParser] the parser instance
-    # @raise [ArgumentError] if given a class without the correct interface
     def response_parser= parser
       @response_parser = case parser
-      when Animoto::ResponseParser
+      when Animoto::ResponseParsers::Base
         parser
       when Class
         if %{format parse unparse}.all? { |m| parser.instance_methods.include? m }
@@ -103,53 +141,62 @@ module Animoto
           raise ArgumentError
         end
       else
-        Animoto::ResponseParser[parser].new
+        Animoto::ResponseParsers[parser].new
       end
     end
     
     # Finds a resource by its URL.
     #
-    # @param [Class] klass the Resource class you're finding
+    # @param [Class] klass the resource class you're finding
     # @param [String] url the URL of the resource you want
-    # @param [Hash] options
-    # @return [Resource] the Resource object found
+    # @param [Hash<Symbol,Object>] options
+    # @return [Resources::Base] the resource object found
     def find klass, url, options = {}
       klass.load(find_request(klass, url, options))
     end
     
+    # Returns a callback object of the specified type given the callback body.
+    #
+    # @param [Class] klass the callback class
+    # @param [String] body the HTTP body of the callback
+    # @return [Callbacks::Base] the callback object
+    def process_callback klass, body
+      klass.new(response_parser.parse(body))
+    end
+    
     # Sends a request to start directing a storyboard.
     #
-    # @param [DirectingManifest] manifest the manifest to direct
-    # @param [Hash] options
-    # @return [DirectingJob] a job to monitor the status of the directing
+    # @param [Manifests::Directing] manifest the manifest to direct
+    # @param [Hash<Symbol,Object>] options
+    # @return [Jobs::Directing] a job to monitor the status of the directing
     def direct! manifest, options = {}
-      DirectingJob.load(send_manifest(manifest, DirectingJob.endpoint, options))
+      Resources::Jobs::Directing.load(send_manifest(manifest, Resources::Jobs::Directing.endpoint, options))
     end
     
     # Sends a request to start rendering a video.
     #
-    # @param [RenderingManifest] manifest the manifest to render
-    # @param [Hash] options
-    # @return [RenderingJob] a job to monitor the status of the rendering
+    # @param [Manifests::Rendering] manifest the manifest to render
+    # @param [Hash<Symbol,Object>] options
+    # @return [Jobs::Rendering] a job to monitor the status of the rendering
     def render! manifest, options = {}
-      RenderingJob.load(send_manifest(manifest, RenderingJob.endpoint, options))
+      Resources::Jobs::Rendering.load(send_manifest(manifest, Resources::Jobs::Rendering.endpoint, options))
     end
     
     # Sends a request to start directing and rendering a video.
     #
-    # @param [DirectingAndRenderingManifest] manifest the manifest to direct and render
-    # @param [Hash] options
-    # @return [DirectingAndRenderingJob] a job to monitor the status of the directing and rendering
+    # @param [Manifests::DirectingAndRendering] manifest the manifest to direct and render
+    # @param [Hash<Symbol,Object>] options
+    # @return [Jobs::DirectingAndRendering] a job to monitor the status of the directing and rendering
     def direct_and_render! manifest, options = {}
-      DirectingAndRenderingJob.load(send_manifest(manifest, DirectingAndRenderingJob.endpoint, options))
+      Resources::Jobs::DirectingAndRendering.load(send_manifest(manifest, Resources::Jobs::DirectingAndRendering.endpoint, options))
     end
     
     # Update a resource with the latest attributes. Useful to update the state of a Job to
     # see if it's ready if you are not using HTTP callbacks.
     #
-    # @param [Resource] resource the resource to update
-    # @param [Hash] options
-    # @return [Resource] the given resource with the latest attributes
+    # @param [Resources::Base] resource the resource to update
+    # @param [Hash<Symbol,Object>] options
+    # @return [Resources::Base] the given resource with the latest attributes
     def reload! resource, options = {}
       resource.load(find_request(resource.class, resource.url, options))
     end
@@ -159,6 +206,7 @@ module Animoto
     # Sets the API credentials from an .animotorc file. First looks for one in the current
     # directory, then checks ~/.animotorc, then finally /etc/.animotorc.
     #
+    # @return [void]
     # @raise [ArgumentError] if none of the files are found
     def configure_from_rc_file
       current_path = Dir.pwd + '/.animotorc'
@@ -183,18 +231,18 @@ module Animoto
     #
     # @param [Class] klass the Resource class you're looking for
     # @param [String] url the URL of the resource
-    # @param [Hash] options
-    # @return [Hash] deserialized response body
+    # @param [Hash<Symbol,Object>] options
+    # @return [Hash<String,Object>] deserialized response body
     def find_request klass, url, options = {}
       request(:get, url, nil, { "Accept" => content_type_of(klass) }, options)
     end
     
     # Builds a request requiring a manifest.
     #
-    # @param [Manifest] manifest the manifest being acted on
+    # @param [Manifests::Base] manifest the manifest being acted on
     # @param [String] endpoint the endpoint to send the request to
-    # @param [Hash] options
-    # @return [Hash] deserialized response body
+    # @param [Hash<Symbol,Object>] options
+    # @return [Hash<String,Object>] deserialized response body
     def send_manifest manifest, endpoint, options = {}
       u = URI.parse(self.endpoint)
       u.path = endpoint
@@ -211,25 +259,30 @@ module Animoto
     #
     # @param [Symbol] method which HTTP method to use (should be lowercase, i.e. :get instead of :GET)
     # @param [String] url the URL of the request
-    # @param [String, nil] body the request body
+    # @param [String,nil] body the request body
     # @param [Hash<String,String>] headers the request headers (will be sent as-is, which means you should
     #   specify "Content-Type" => "..." instead of, say, :content_type => "...")
-    # @param [Hash] options
-    # @return [Hash] deserialized response body
+    # @param [Hash<Symbol,Object>] options
+    # @return [Hash<String,Object>] deserialized response body
     # @raise [Error]
     def request method, url, body, headers = {}, options = {}
-      error = catch(:fail) do
+      code, body = catch(:fail) do
         options = { :username => @key, :password => @secret }.merge(options)
         @logger.info "Sending request to #{url.inspect} with body #{body}"
         response = http_engine.request(method, url, body, headers, options)
         @logger.info "Received response #{response}"
         return response_parser.parse(response)
       end
-      if error
-        errors = response_parser.parse(error)['response']['status']['errors']
-        err_string = errors.collect { |e| e['message'] }.join(', ')
-        @logger.error "Error response from server: #{err_string}"
-        raise Animoto::Error.new(err_string)
+      if code
+        if body.empty?
+          @logger.error "HTTP error (#{code})"
+          raise Animoto::Error.new("HTTP error (#{code})")
+        else
+          errors = response_parser.parse(body)['response']['status']['errors']
+          err_string = errors.collect { |e| e['message'] }.join(', ')
+          @logger.error "Error response from server: #{err_string}"
+          raise Animoto::Error.new(err_string)
+        end
       else
         @logger.error "Error sending request to #{url.inspect}"
         raise Animoto::Error
@@ -240,7 +293,7 @@ module Animoto
     end
     
     # Creates the full content type string given a Resource class or instance
-    # @param [Class,ContentType] klass_or_instance the class or instance to build the
+    # @param [Class,Support::ContentType] klass_or_instance the class or instance to build the
     #   content type for
     # @return [String] the full content type with the version and format included (i.e.
     #   "application/vnd.animoto.storyboard-v1+json")