animoto 1.0.0 → 1.1.0

data/README.md

@@ -156,8 +156,8 @@ status.
     
     # Poll the service until the directing job is done.
     while directing_job.pending?
-    	sleep(30)
-    	client.reload!(directing_job)
+      sleep(30)
+      client.reload!(directing_job)
     end
 
     # If the directing job finished successfully, there will be a "storyboard" 
@@ -166,37 +166,105 @@ status.
     
       # Now it's time to render the storyboard into a video.  First we create
       # a rendering manifest.
-    	manifest = Manifests::Rendering.new(
-    	  storyboard,
-    	  :resolution => "720p",
-    	  :framerate => 24,
-    	  :format => 'h264'
-    	)
-    	
-    	# Send the manifest to the API.
-    	rendering_job = client.render!(manifest)
-    	
-    	# Poll the service until the rendering job is done
-    	while rendering_job.pending?
-    		sleep(30)
-    		client.reload!(rendering_job)
-    	end
+      manifest = Manifests::Rendering.new(
+        storyboard,
+        :resolution => "720p",
+        :framerate => 24,
+        :format => 'h264'
+      )
+      
+      # Send the manifest to the API.
+      rendering_job = client.render!(manifest)
+      
+      # Poll the service until the rendering job is done
+      while rendering_job.pending?
+        sleep(30)
+        client.reload!(rendering_job)
+      end
 
       # If the job has a video associated with it, everything worked out ok.
-    	if video = rendering_job.video
-    	  # Print a link to download the video file.
-    	  client.reload!(video)
-    		puts video.download_url
-    	else
-    	  # Something happened during rendering...
-    		raise rendering_job.errors.first
-    	end
+      if video = rendering_job.video
+        # Print a link to download the video file.
+        client.reload!(video)
+        puts video.download_url
+      else
+        # Something happened during rendering...
+        raise rendering_job.errors.first
+      end
     else
       # Looks like there was a problem. Perhaps one of the assets wasn't 
       # retrieved or was corrupt...
-    	raise directing_job.errors.first
+      raise directing_job.errors.first
     end
 
+### Storyboard bundling example
+
+Bundling is a process used for exporting an Animoto storyboard. The bundling process packages
+up all the information used by Animoto to render videos into a single file, the storyboard
+bundle. This file is essentially just a zip file with a special structure. After a storyboard
+bundle has been created and retrieved by your system, the original storyboard can be deleted.
+Later, the storyboard bundle can be reconstituted into an Animoto storyboard so that videos may
+be rendered.
+
+    require 'animoto/client'
+    include Animoto
+    
+    client = Client.new("key", "secret")
+    
+    # Make a directing manifest and direct it as detailed above.
+    # Afterwards, we can make a StoryboardBundling manifest and bundle up the
+    # storyboard we just made.
+    
+    storyboard = directing_job.storyboard
+    bundling_manifest = Manifests::StoryboardBundling.new(storyboard)
+    bundling_job = client.bundle!(bundling_manifest)
+    
+    # Poll the service until the bundling job is complete.
+    # As with all jobs, HTTP callbacks are also supported, but we're just
+    # going for a simple example here.
+    while bundling_job.pending?
+      sleep(30)
+      client.reload!(bundling_job)
+    end
+    
+    # The bundle_url returned points to where you can download the storyboard
+    # bundle. Downloading the bundle and archiving it elsewhere is outside the
+    # scope of the client's functionality.
+    puts bundling_job.bundle_url
+    
+    # After you have a handle for the storyboard bundle, the original storyboard
+    # can be deleted.
+    client.delete!(storyboard)
+    
+Turning a bundle back into a storyboard is just as simple.
+
+    require 'animoto/client'
+    include Animoto
+    
+    client = Client.new("key", "secret")
+    
+    # Make a storyboard unbundling manifest with the url to your archived storyboard bundle.
+    unbundling_manifest = Manifest::StoryboardUnbundling.new(:bundle_url => "http://your-storage-solution.com/path/to/your/bundle")
+    unbundling_job = client.unbundle!(unbundling_manifest)
+    
+    # Poll the service until unbundling is complete.
+    while unbundling_job.pending?
+      sleep(30)
+      client.reload!(unbundling_job)
+    end
+    
+    # Now you can use the storyboard to render a video.
+    rendering_manifest = Manifests::Rendering.new(
+      unbundling_job.storyboard,
+      :resolution => "720p",
+      :framerate => 24,
+      :format => 'h264'
+    )
+    rendering_job = client.render!(rendering_manifest)
+    
+    # Now proceed with using your render as detailed above.
+    
+
 <a name="how_to_contribute"></a>
 ## How to contribute to this client
 
@@ -229,4 +297,4 @@ IN NO EVENT SHALL ANIMOTO BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY SPECIAL, P
 
 You agree to indemnify defend and hold Animoto, its parents, subsidiaries, affiliates, officers and employees, harmless from any liabilities, claims, expenses or demands, including reasonable attorneys’ fees and costs, made by any third party due to or arising out of your use of this software, derivative works created by you, the violation of laws, rules, regulations or these terms, and the infringement of any intellectual property right by your derivative works or by you.
 
-[api_docs]: http://animoto.com/developer/api
+[api_docs]: http://api-documentation.animoto.com/index.html

data/lib/animoto/client.rb

@@ -18,6 +18,8 @@ require 'animoto/resources/jobs/base'
 require 'animoto/resources/jobs/directing_and_rendering'
 require 'animoto/resources/jobs/directing'
 require 'animoto/resources/jobs/rendering'
+require 'animoto/resources/jobs/storyboard_bundling'
+require 'animoto/resources/jobs/storyboard_unbundling'
 
 require 'animoto/assets/base'
 require 'animoto/assets/footage'
@@ -29,6 +31,8 @@ require 'animoto/manifests/base'
 require 'animoto/manifests/directing'
 require 'animoto/manifests/directing_and_rendering'
 require 'animoto/manifests/rendering'
+require 'animoto/manifests/storyboard_bundling'
+require 'animoto/manifests/storyboard_unbundling'
 
 require 'animoto/http_engines/base'
 require 'animoto/response_parsers/base'
@@ -37,7 +41,7 @@ module Animoto
   class Client
     
     # The default endpoint where requests go.
-    API_ENDPOINT      = "https://api2-sandbox.animoto.com/"
+    API_ENDPOINT      = "https://platform-sandbox.animoto.com/"
     
     # The version of the Animoto API this client targets.
     API_VERSION       = 1
@@ -185,6 +189,24 @@ module Animoto
       Resources::Jobs::DirectingAndRendering.load(send_manifest(manifest, Resources::Jobs::DirectingAndRendering.endpoint, options))
     end
     
+    # Sends a request to bundle a storyboard.
+    #
+    # @param [Manifests::StoryboardBundling] manifest the manifest to bundle
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Jobs::StoryboardBundling] a job to monitor the status of the storyboard bundling
+    def bundle! manifest, options = {}
+      Resources::Jobs::StoryboardBundling.load(send_manifest(manifest, Resources::Jobs::StoryboardBundling.endpoint, options))
+    end
+
+    # Sends a request to unbundle a storyboard.
+    #
+    # @param [Manifests::StoryboardUnbundling] manifest the manifest to unbundle
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Jobs::StoryboardUnbundling] a job to monitor the status of the storyboard unbundling
+    def unbundle! manifest, options = {}
+      Resources::Jobs::StoryboardUnbundling.load(send_manifest(manifest, Resources::Jobs::StoryboardUnbundling.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.
     #
@@ -195,6 +217,15 @@ module Animoto
       resource.load(find_request(resource.class, resource.url, options))
     end
     
+    # Delete a resource. May not supported for all types of resources.
+    #
+    # @param [Resources::Base] resource to delete
+    # @param [Hash{Symbol=>Object}] options
+    # @return [Boolean] true if deletion was successful
+    def delete! resource, options = {}
+      request(:delete, resource.url, nil)
+    end
+    
     private
     
     # Sets the API credentials from an .animotorc file. First looks for one in the current
@@ -208,7 +239,6 @@ module Animoto
       config = if File.exist?(current_path)
         YAML.load(File.read(current_path))
       elsif File.exist?(home_path)
-        home_path = File.expand_path '~/.animotorc'
         YAML.load(File.read(home_path))
       elsif File.exist?('/etc/.animotorc')
         YAML.load(File.read('/etc/.animotorc'))
@@ -244,7 +274,7 @@ module Animoto
         :post,
         u.to_s,
         response_parser.unparse(manifest.to_hash),
-        { "Accept" => "application/#{response_parser.format}", "Content-Type" => content_type_of(manifest) },
+        { "Accept" => content_type_of(manifest.associated_job_class), "Content-Type" => content_type_of(manifest) },
         options
       )
     end
@@ -257,33 +287,25 @@ module Animoto
     # @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{Symbol=>Object}] options
-    # @return [Hash{String=>Object}] deserialized response body
-    # @raise [Error]
+    # @return [Hash{String=>Object},Boolean] deserialized response body, or boolean indicating success or failure
+    # @raise [HTTPError] if something goes wrong with the request or response
     def request method, url, body, headers = {}, options = {}
-      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 code
-        if body.empty?
-          @logger.error "HTTP error (#{code})"
-          raise Animoto::Error.new("HTTP error (#{code})")
+      options = { :username => @key, :password => @secret }.merge(options)
+      @logger.info "Sending request to #{url.inspect} with body #{body}"
+      code, response_body = http_engine.request(method, url, body, headers, options)
+      if method == :head
+        (200..299) === code || raise(Animoto::HTTPError.new(url, code))
+      else
+        case code
+        when 204, 205
+          true
+        when (200..299)
+          response_parser.parse(response_body)
         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)
+          parsed_response = begin response_body ? response_parser.parse(response_body) : nil rescue nil end
+          raise Animoto::HTTPError.new(url, code, parsed_response)
         end
-      else
-        @logger.error "Error sending request to #{url.inspect}"
-        raise Animoto::Error
       end
-    rescue NoMethodError => e
-      @logger.error e.inspect
-      raise Animoto::Error.new("Invalid response (#{e.inspect})")
     end
     
     # Creates the full content type string given a Resource class or instance

data/lib/animoto/http_engines/base.rb

@@ -26,23 +26,11 @@ module Animoto
       # @option options [Integer] :timeout set a timeout
       # @option options [String] :username the authentication username
       # @option options [String] :password the authentication password
-      # @return [String] the response body
+      # @return [Array[Integer,String]] array of status code and response body
       # @raise [AbstractMethodError] if called on the abstract class
       def request method, url, body = nil, headers = {}, options = {}
         raise AbstractMethodError
-      end
-    
-      private
-    
-      # Checks the response and raises an error if the status isn't success.
-      #
-      # @param [Integer] code the HTTP status code
-      # @param [String] body the HTTP response body
-      # @return [void]
-      # @raise [Animoto::Error] if the status isn't between 200 and 299
-      def check_response code, body
-        throw(:fail, [code,body]) unless (200..299).include?(code)
-      end
+      end    
     end
   end
 end

data/lib/animoto/http_engines/curl_adapter.rb

@@ -8,8 +8,7 @@ module Animoto
       def request method, url, body = nil, headers = {}, options = {}
         curl = build_curl method, url, body, headers, options
         perform curl, method, body
-        check_response curl.response_code, curl.body_str
-        curl.body_str
+        [curl.response_code, curl.body_str]
       end
       
       private
@@ -23,10 +22,14 @@ module Animoto
       # @return [Curl::Easy] the Easy instance
       def build_curl method, url, body, headers, options
         ::Curl::Easy.new(url) do |c|
+          c.http_auth_types = Curl::CURLAUTH_BASIC
           c.username = options[:username]
           c.password = options[:password]
           c.timeout = options[:timeout]
           c.post_body = body
+          c.ssl_verify_host = false
+          c.ssl_verify_peer = false
+          c.proxy_url = options[:proxy]
           headers.each { |header, value| c.headers[header] = value }
         end
       end
@@ -39,10 +42,16 @@ module Animoto
       # @return [void]
       def perform curl, method, body
         case method
+        when :head
+          curl.http_head
         when :get
           curl.http_get
         when :post
           curl.http_post(body)
+        when :put
+          curl.http_put(body)
+        when :delete
+          curl.http_delete
         end
       end
     end    

data/lib/animoto/http_engines/net_http_adapter.rb

@@ -7,18 +7,20 @@ module Animoto
       
       # A map of HTTP verb symbols to the Net::HTTP classes that handle them.
       HTTP_METHOD_MAP   = {
-        :get  => Net::HTTP::Get,
-        :post => Net::HTTP::Post
+        :head   => Net::HTTP::Head,
+        :get    => Net::HTTP::Get,
+        :post   => Net::HTTP::Post,
+        :put    => Net::HTTP::Put,
+        :delete => Net::HTTP::Delete
       }
       
       # @return [String]
       def request method, url, body = nil, headers = {}, options = {}
         uri = URI.parse(url)
-        http = build_http uri
+        http = build_http uri, options
         req = build_request method, uri, body, headers, options        
         response = http.request req
-        check_response response.code.to_i, response.body
-        response.body
+        [response.code.to_i, response.body]
       end
       
       private
@@ -27,8 +29,14 @@ module Animoto
       #
       # @param [URI] uri a URI object of the request URL
       # @return [Net::HTTP] the HTTP object
-      def build_http uri
-        http = Net::HTTP.new uri.host, uri.port
+      def build_http uri, options
+        http = if options[:proxy]
+          proxy_uri = URI.parse(options[:proxy])
+          Net::HTTP::Proxy(proxy_uri.host, proxy_uri.port).new uri.host, uri.port
+        else
+          Net::HTTP.new uri.host, uri.port
+        end
+        http.read_timeout = options[:timeout]
         http.use_ssl = true
         http.verify_mode = OpenSSL::SSL::VERIFY_NONE
         http

data/lib/animoto/http_engines/patron_adapter.rb

@@ -8,8 +8,7 @@ module Animoto
       def request method, url, body = nil, headers = {}, options = {}
         session = build_session options
         response = session.request method, url, headers, :data => body
-        check_response response.status, response.body
-        response.body
+        [response.status, response.body]
       end
       
       private

data/lib/animoto/http_engines/rest_client_adapter.rb

@@ -6,6 +6,7 @@ module Animoto
       
       # @return [String]
       def request method, url, body = nil, headers = {}, options = {}
+        RestClient.proxy = options[:proxy]
         response = ::RestClient::Request.execute({
           :method => method,
           :url => url,
@@ -15,8 +16,7 @@ module Animoto
           :password => options[:password],
           :timeout => options[:timeout]
         })
-        check_response response.code, response.body
-        response.body
+        [response.code, response.body]
       end
     end    
   end

data/lib/animoto/http_engines/typhoeus_adapter.rb

@@ -12,10 +12,11 @@ module Animoto
           :headers => headers,
           :timeout => options[:timeout],
           :username => options[:username],
-          :password => options[:password]
+          :password => options[:password],
+          :disable_ssl_peer_verification => true,
+          :proxy => options[:proxy]
         })
-        check_response response.code, response.body
-        response.body
+        [response.code, response.body]
       end   
     end    
   end

data/lib/animoto/manifests/base.rb

@@ -4,12 +4,40 @@ module Animoto
     # @abstract
     class Base
       include Support::ContentType
-    
+            
       # @return [String]
       def self.infer_content_type
         super + '_manifest'
       end
-            
+      
+      # Returns the Resources::Jobs::Base descendant class associated with this manifest class
+      # (that is, the type of job returned when a manifest of this type is posted).
+      #
+      # @example
+      #   Manifests::Directing.associated_job_class # => Resources::Jobs::Directing
+      # @return [Class] the associated job class
+      def self.associated_job_class
+        Resources::Jobs.const_get(self.name.split('::').last)
+      end
+    
+      # A URL to receive a callback after directing is finished.
+      # @return [String]
+      attr_accessor :http_callback_url
+      
+      # The format of the callback; either 'xml' or 'json'.
+      # @return [String]
+      attr_accessor :http_callback_format
+
+      # Creates a new manifest
+      #
+      # @param [Hash{Symbol=>Object}] options
+      # @option options [String] :http_callback_url a URL to receive a callback when this job is done
+      # @option options [String] :http_callback_format the format of the callback
+      def initialize options = {}
+        @http_callback_url  = options[:http_callback_url]
+        @http_callback_format = options[:http_callback_format]
+      end
+
       # Returns a representation of this manifest as a Hash, used to populate
       # request bodies when directing, rendering, etc.
       #
@@ -17,7 +45,29 @@ module Animoto
       def to_hash
         {}
       end
-    
+      
+      # Returns the Resources::Jobs::Base descendant class associated with this manifest (that is,
+      # the type of job that will be returned when this manifest is posted).
+      #
+      # @return [Class] the associated job class
+      def associated_job_class
+        self.class.associated_job_class
+      end
+      
+      private
+      
+      # Helper method to put the standard HTTP callback information into the manifest hash
+      #
+      # @param [Hash{String=>Object}] job_hash the hash version of the 'job' portion of this manifest
+      # @return [void]
+      # @raise [ArgumentError] if a callback url is specified but not the format
+      def add_callback_information job_hash
+        if http_callback_url
+          raise ArgumentError, "You must specify a http_callback_format (either 'xml' or 'json')" if http_callback_format.nil?
+          job_hash['http_callback'] = http_callback_url
+          job_hash['http_callback_format'] = http_callback_format
+        end
+      end
     end
   end
 end

data/lib/animoto/manifests/directing.rb

@@ -11,14 +11,6 @@ module Animoto
       # @return [String]
       attr_accessor :pacing
       
-      # A URL to receive a callback after directing is finished.
-      # @return [String]
-      attr_accessor :http_callback_url
-      
-      # The format of the callback; either 'xml' or 'json'.
-      # @return [String]
-      attr_accessor :http_callback_format
-
       # The array of Visual objects in this manifest.
       # @return [Array<Support::Visual>]
       attr_reader   :visuals
@@ -40,13 +32,12 @@ module Animoto
       # @option options [String] :http_callback_format the format of the callback
       # @return [Manifests::Directing] the manifest
       def initialize options = {}
+        super
         @title      = options[:title]
         @pacing     = options[:pacing] || 'default'
         @style      = 'original'
         @visuals    = []
         @song       = nil
-        @http_callback_url  = options[:http_callback_url]
-        @http_callback_format = options[:http_callback_format]
       end
 
       # Adds a TitleCard to this manifest.
@@ -55,7 +46,7 @@ module Animoto
       # @return [Assets::TitleCard] the new TitleCard
       # @see Animoto::Assets::TitleCard#initialize
       def add_title_card *args
-        card = Assets::TitleCard.new *args
+        card = Assets::TitleCard.new(*args)
         @visuals << card
         card
       end
@@ -66,7 +57,7 @@ module Animoto
       # @return [Assets::Image] the new Image
       # @see Animoto::Assets::Image#initialize
       def add_image *args
-        image = Assets::Image.new *args
+        image = Assets::Image.new(*args)
         @visuals << image
         image
       end
@@ -77,7 +68,7 @@ module Animoto
       # @return [Assets::Footage] the new Footage
       # @see Animoto::Assets::Footage#initialize
       def add_footage *args
-        footage = Assets::Footage.new *args
+        footage = Assets::Footage.new(*args)
         @visuals << footage
         footage
       end
@@ -89,7 +80,7 @@ module Animoto
       # @return [Assets::Song] the new Song
       # @see Animoto::Assets::Song#initialize
       def add_song *args
-        @song = Assets::Song.new *args
+        @song = Assets::Song.new(*args)
       end
 
       # Adds a visual/song to this manifest.
@@ -124,11 +115,7 @@ module Animoto
       def to_hash options = {}
         hash = { 'directing_job' => { 'directing_manifest' => {} } }
         job  = hash['directing_job']
-        if http_callback_url
-          raise ArgumentError, "You must specify a http_callback_format (either 'xml' or 'json')" if http_callback_format.nil?
-          job['http_callback'] = http_callback_url
-          job['http_callback_format'] = http_callback_format
-        end
+        add_callback_information job
         manifest = job['directing_manifest']
         manifest['style'] = style
         manifest['pacing'] = pacing if pacing

data/lib/animoto/manifests/directing_and_rendering.rb

@@ -13,14 +13,6 @@ module Animoto
       # @return [Manifests::Rendering]
       attr_reader :rendering_manifest
 
-      # A URL to receive a callback after directing is finished.
-      # @return [String]
-      attr_accessor :http_callback_url
-      
-      # The format of the callback; either 'xml' or 'json'.
-      # @return [String]
-      attr_accessor :http_callback_format
-
       # Creates a new directing-and-rendering manifest.
       #
       # @param [Hash{Symbol=>Object}] options
@@ -31,12 +23,11 @@ module Animoto
       # @option options [String] :format the format of the rendered video
       # @option options [String] :http_callback_url a URL to receive a callback when this job is done
       # @option options [String] :http_callback_format the format of the callback
-      def initialize options = {}        
+      # @return [Manifests::DirectingAndRendering] the manifest
+      def initialize options = {}
+        super
         @directing_manifest = Manifests::Directing.new(options.only(:title, :pacing))
         @rendering_manifest = Manifests::Rendering.new(options.only(:resolution, :framerate, :format))
-        
-        @http_callback_url  = options[:http_callback_url]
-        @http_callback_format = options[:http_callback_format]
       end
 
       # Delegates method calls to the underlying directing or rendering manifests if
@@ -46,9 +37,9 @@ module Animoto
       def method_missing *args
         name = args.first
         if directing_manifest.respond_to?(name)
-          directing_manifest.__send__ *args
+          directing_manifest.__send__(*args)
         elsif rendering_manifest.respond_to?(name)
-          rendering_manifest.__send__ *args
+          rendering_manifest.__send__(*args)
         else
           super
         end
@@ -63,11 +54,7 @@ module Animoto
       def to_hash options = {}
         hash  = { 'directing_and_rendering_job' => {} }
         job   = hash['directing_and_rendering_job']
-        if http_callback_url
-          raise ArgumentError, "You must specify a http_callback_format (either 'xml' or 'json')" if http_callback_format.nil?
-          job['http_callback'] = http_callback_url
-          job['http_callback_format'] = http_callback_format
-        end
+        add_callback_information job
         job['directing_manifest'] = self.directing_manifest.to_hash['directing_job']['directing_manifest']
         job['rendering_manifest'] = self.rendering_manifest.to_hash['rendering_job']['rendering_manifest']
         hash