animoto 0.1.1.beta1 → 1.0.0

data/lib/animoto/manifests/rendering.rb

@@ -8,7 +8,7 @@ module Animoto
       attr_accessor :resolution
       
       # The framerate of the rendered video. Valid values are 12, 15, 24 or 30.
-      # @return [Fixnum]
+      # @return [Integer]
       attr_accessor :framerate
       
       # The format of the rendered video. Valid values are 'h264', 'h264-iphone', 'flv' or 'iso'.
@@ -30,15 +30,16 @@ module Animoto
       # Creates a new rendering manifest.
       #
       # @param [Resources::Storyboard] storyboard the storyboard for this rendering
-      # @param [Hash<Symbol,Object>] options
+      # @param [Hash{Symbol=>Object}] options
       # @option options [String] :resolution the vertical resolution of the rendered video
       # @option options [Integer] :framerate the framerate of the rendered video
       # @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
       # @return [Manifests::Rendering] the manifest
-      def initialize storyboard, options = {}
-        @storyboard = storyboard
+      def initialize *args
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        @storyboard = args.shift
         @resolution = options[:resolution]
         @framerate  = options[:framerate]
         @format     = options[:format]
@@ -48,7 +49,7 @@ module Animoto
     
       # Returns a representation of this manifest as a Hash.
       #
-      # @return [Hash<String,String>] this manifest as a Hash
+      # @return [Hash{String=>Object}] this manifest as a Hash
       # @raise [ArgumentError] if a callback URL was specified but not the format
       def to_hash
         hash  = { 'rendering_job' => { 'rendering_manifest' => { 'rendering_parameters' => {} } } }
@@ -59,7 +60,7 @@ module Animoto
           job['http_callback_format'] = http_callback_format
         end
         manifest = job['rendering_manifest']
-        manifest['storyboard_url'] = storyboard.url
+        manifest['storyboard_url'] = storyboard.url if storyboard
         params = manifest['rendering_parameters']
         params['resolution'] = resolution
         params['framerate'] = framerate

data/lib/animoto/resources/base.rb

@@ -1,7 +1,7 @@
 module Animoto
   module Resources
 
-    # @abstract Set {#endpoint} and maybe override {Support::StandardEnvelope#unpack_standard_envelope} to subclass.
+    # @abstract Set {#endpoint} and maybe override {Support::StandardEnvelope::ClassMethods#unpack_standard_envelope} to subclass.
     class Base
       include Support::StandardEnvelope
     
@@ -34,7 +34,7 @@ module Animoto
       # raise an error.
       #
       # @private
-      # @param [Hash<String,Object>] body the deserialized response body
+      # @param [Hash{String=>Object}] body the deserialized response body
       # @return [Resources::Base] an instance of this class
       def self.load body
         new unpack_standard_envelope(body)
@@ -52,7 +52,7 @@ module Animoto
         #   storyboard2 = client.find! Animoto::Resources::Storyboard, "https://api.animoto.com/storyboards/1"
         #   storyboard1.equal?(storyboard2) # => true
         #
-        # @param [Hash<String,Object>] attributes a hash of attributes for this resource
+        # @param [Hash{String=>Object}] attributes a hash of attributes for this resource
         # @return [Resources::Base] either a new Resource instance, or an existing one with updated
         #   attributes
         alias_method :original_new, :new
@@ -79,7 +79,7 @@ module Animoto
 
         # Returns (or vivifies) the identity map for this class.
         #
-        # @return [Hash<String,Resources::Base>] the identity map
+        # @return [Hash{String=>Resources::Base}] the identity map
         def instances
           @instances ||= {}
         end
@@ -89,7 +89,7 @@ module Animoto
 
       # Creates a new resource.
       #
-      # @param [Hash<String,Object>] attributes hash of attributes for this resource
+      # @param [Hash{String=>Object}] attributes hash of attributes for this resource
       # @see #instantiate
       # @return [Resources::Base] the resource
       def initialize attributes = {}
@@ -99,7 +99,7 @@ module Animoto
       # Update this instance with new attributes from the response body.
       #
       # @private
-      # @param [Hash<String,Object>] body deserialized from a response body
+      # @param [Hash{String=>Object}] body deserialized from a response body
       # @return [self] this instance, updated
       def load body = {}
         instantiate unpack_standard_envelope(body)
@@ -110,7 +110,7 @@ module Animoto
       # of #initialize.
       #
       # @private
-      # @param [Hash<Symbol,Object>] attributes hash of attributes for this resource
+      # @param [Hash{Symbol=>Object}] attributes hash of attributes for this resource
       # @return [self] this instance
       def instantiate attributes = {}
         @errors = (attributes[:errors] || []).collect { |e| wrap_error e  }      
@@ -123,7 +123,7 @@ module Animoto
     
       # Turns an error from a response body into a Ruby object.
       #
-      # @param [Hash<String,Object>] error the error "object" from a response body
+      # @param [Hash{String=>Object}] error the error "object" from a response body
       # @return [Animoto::Error] a Ruby error object
       def wrap_error error
         Animoto::Error.new error['message']

data/lib/animoto/resources/jobs/base.rb

@@ -5,9 +5,9 @@ module Animoto
       # @abstract
       class Base < Animoto::Resources::Base
         
-        # @return [Hash<Symbol,Object>]
+        # @return [Hash{Symbol=>Object}]
         def self.unpack_standard_envelope body
-          super.merge(:state => body['response']['payload'][payload_key]['state'])
+          super.merge(:state => unpack_payload(body)['state'])
         end
         
         # @return [String]

data/lib/animoto/resources/jobs/directing.rb

@@ -5,13 +5,18 @@ module Animoto
     
         endpoint '/jobs/directing'
 
-        # @return [Hash<Symbol,Object>]
+        # @return [Hash{Symbol=>Object}]
         # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
         def self.unpack_standard_envelope body
-          super.merge(:storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'])
+          super.merge(:storyboard_url => unpack_links(body)['storyboard'])
         end
     
+        # The Storyboard created by this job.
+        # @return [Resources::Storyboard]
         attr_reader :storyboard
+        
+        # The URL for this storyboard resource created by this job.
+        # @return [String]
         attr_reader :storyboard_url
 
         # @return [Jobs::Directing]

data/lib/animoto/resources/jobs/directing_and_rendering.rb

@@ -5,20 +5,46 @@ module Animoto
     
         endpoint '/jobs/directing_and_rendering'
 
-        # @return [Hash<Symbol,Object>]
+        # @return [Hash{Symbol=>Object}]
         # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
-        def self.unpack_standard_envelope body
-          super.merge(:video_url => body['response']['payload'][payload_key]['links']['video'])
+        def self.unpack_standard_envelope body = {}
+          links = unpack_links(body)
+          super.merge({
+            :storyboard_url => links['storyboard'],
+            :video_url      => links['video']
+          })
         end
-    
-        attr_reader :video
+
+        # The URL for the storyboard created for this job. This storyboard can be
+        # used into future rendering jobs to produce different formats, resolutions,
+        # etc.
+        # @return [String]
+        attr_reader :storyboard_url
+        
+        # A Storyboard object for this job.
+        # @return [Resources::Storyboard]
+        attr_reader :storyboard
+        
+        # The URL for the video created. Note that this is for the video *resource* and not
+        # the URL to the actual video *file* (though requesting the resource will give you
+        # the URL to the file).
+        # @return [String]
         attr_reader :video_url
-    
+        
+        # A Video object for this job.
+        #
+        # @note this object may not have all the most recent attributes, namely the download_url
+        #   attribute. Use {Client#reload!} to update the object.
+        # @return [Resources::Video]
+        attr_reader :video
+
         # @return [Jobs::DirectingAndRendering]
         # @see Animoto::Jobs::Base#instantiate
         def instantiate attributes = {}
-          @video_url = attributes[:video_url]
-          @video = Animoto::Resources::Video.new(:url => @video_url) if @video_url
+          @storyboard_url = attributes[:storyboard_url]
+          @storyboard     = Animoto::Resources::Storyboard.new(:url => @storyboard_url) if @storyboard_url
+          @video_url      = attributes[:video_url]
+          @video          = Animoto::Resources::Video.new(:url => @video_url) if @video_url
           super
         end
     

data/lib/animoto/resources/jobs/rendering.rb

@@ -5,18 +5,32 @@ module Animoto
     
         endpoint '/jobs/rendering'
 
-        # @return [Hash<Symbol,Object>]
+        # @return [Hash{Symbol=>Object}]
         # @see Animoto::Support::StandardEvelope::ClassMethods#unpack_standard_envelope
         def self.unpack_standard_envelope body
+          links = unpack_links(body)
           super.merge({
-            :storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'],
-            :video_url      => body['response']['payload'][payload_key]['links']['video']
+            :storyboard_url => links['storyboard'],
+            :video_url      => links['video']
           })
         end
     
+        # The Storyboard this job will render a video from.
+        # @return [Resources::Storyboard]
         attr_reader :storyboard
+        
+        # The URL to the storyboard resource.
+        # @return [String]
         attr_reader :storyboard_url
+        
+        # The Video created by this job.
+        # @return [Resources::Video]
         attr_reader :video
+        
+        # The URL to the video resource.
+        #
+        # @note This URL points to the video *resource* and not the actual video *file*.
+        # @return [String]
         attr_reader :video_url
     
         # @return [Jobs::Rendering]

data/lib/animoto/resources/storyboard.rb

@@ -2,18 +2,34 @@ module Animoto
   module Resources
     class Storyboard < Animoto::Resources::Base
       
-      # @return [Hash<Symbol,Object>]
+      # @private
+      # @return [Hash{String=>Object}]
+      # @see Animoto::Support::Support::ClassMethods#unpack_standard_envelope
+      def self.unpack_metadata body = {}
+        unpack_payload(body)['metadata'] || {}
+      end
+      
+      # @return [Hash{Symbol=>Object}]
       # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
       def self.unpack_standard_envelope body = {}
+        metadata = unpack_metadata(body)
         super.merge({
-          :duration => body['response']['payload'][payload_key]['metadata']['duration'],
-          :visuals_count => body['response']['payload'][payload_key]['metadata']['visuals_count'],
-          :preview_url => body['response']['payload'][payload_key]['links']['preview']
+          :duration       => metadata['duration'],
+          :visuals_count  => metadata['visuals_count'],
+          :preview_url    => unpack_links(body)['preview']
         })
       end
     
+      # The duration (in seconds) that the video, once rendered, will be.
+      # @return [Float]
       attr_reader :duration
+      
+      # The number of visuals (title cards, images, etc.) in this storyboard.
+      # @return [Integer]
       attr_reader :visuals_count
+      
+      # If available, the URL to the low-resolution 'preview' video.
+      # @return [String]
       attr_reader :preview_url
       
       # Sets the attributes for a new storyboard.

data/lib/animoto/resources/video.rb

@@ -1,34 +1,57 @@
 module Animoto
   module Resources
     class Video < Animoto::Resources::Base
+
+      # @private
+      # @return [Hash{String=>Object}]
+      # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
+      def self.unpack_rendering_parameters body
+        (unpack_payload(body)['metadata'] || {})['rendering_parameters']
+      end
     
-      # @return [Hash<Symbol,Object>]
+      # @return [Hash{Symbol=>Object}]
       # @see Animoto::Support::StandardEnvelope::ClassMethods#unpack_standard_envelope
       def self.unpack_standard_envelope body
+        links = unpack_links(body)
+        params = unpack_rendering_parameters(body)
         super.merge({
-          :download_url => body['response']['payload'][payload_key]['links']['file'],
-          :storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'],
-          :duration => body['response']['payload'][payload_key]['metadata']['duration'],
-          :format   => body['response']['payload'][payload_key]['metadata']['format'],
-          :framerate  => body['response']['payload'][payload_key]['metadata']['framerate'],
-          :resolution => body['response']['payload'][payload_key]['metadata']['vertical_resolution']
+          :download_url   => links['file'],
+          :storyboard_url => links['storyboard'],
+          :format         => params['format'],
+          :framerate      => params['framerate'],
+          :resolution     => params['resolution']
         })
       end
 
+      # The URL to the video file.
+      # @return [String]
       attr_reader :download_url
+      
+      # The URL to the storyboard resource this video was rendered from.
+      # @return [String]
       attr_reader :storyboard_url
+      
+      # The Storyboard object this video was rendered from.
+      # @return [Resources::Storyboard]
       attr_reader :storyboard
-      attr_reader :duration
+      
+      # The format of the video.
+      # @return [String]
       attr_reader :format
+      
+      # The framerate of the video.
+      # @return [Integer]
       attr_reader :framerate
+      
+      # The resolution of the video.
+      # @return [String]
       attr_reader :resolution
 
       # Sets the attributes on a new video.
       #
-      # @param [Hash<Symbol,Object>] attributes
+      # @param [Hash{Symbol=>Object}] attributes
       # @option attributes [String] :download_url the URL where this video can be downloaded
       # @option attributes [String] :storyboard_url the URL for this video's storyboard
-      # @option attributes [Integer] :duration the duration (in seconds) of this video
       # @option attributes [String] :format the format of this video
       # @option attributes [Integer] :framerate the framerate of this video
       # @option attributes [String] :resolution the vertical resolution of this video
@@ -38,7 +61,6 @@ module Animoto
         @download_url = attributes[:download_url]
         @storyboard_url = attributes[:storyboard_url]
         @storyboard = Animoto::Resources::Storyboard.new(:url => @storyboard_url) if @storyboard_url
-        @duration = attributes[:duration]
         @format = attributes[:format]
         @framerate = attributes[:framerate]
         @resolution = attributes[:resolution]

data/lib/animoto/response_parsers/base.rb

@@ -1,8 +1,13 @@
 module Animoto
   module ResponseParsers    
-    extend Support::DynamicClassLoader(File.expand_path(File.dirname(__FILE__)))
+    extend Support::DynamicClassLoader
     
-    # @abstract Override {#parse} and {#unparse} to subclass.
+    dynamic_class_path File.expand_path(File.dirname(__FILE__))
+    
+    adapter 'JSON'
+    adapter 'Yajl'
+    
+    # @abstract Override {#parse}, {#unparse}, and {#format} (or set @format on the class) to subclass.
     class Base
     
       # Returns the format of this parser class.
@@ -23,20 +28,20 @@ module Animoto
       #
       # @abstract
       # @param [String] body the HTTP response body
-      # @return [Hash<String,Object>] the parsed response
-      # @raise [NotImplementedError] if called on the abstract class
+      # @return [Hash{String=>Object}] the parsed response
+      # @raise [AbstractMethodError] if called on the abstract class
       def parse body
-        raise NotImplementedError
+        raise AbstractMethodError
       end
     
       # Serializes a Hash into the format for this parser.
       #
       # @abstract
-      # @param [Hash<Object,Object>] hash the hash to serialize
+      # @param [Hash{Object=>Object}] hash the hash to serialize
       # @return [String] the serialized data
-      # @raise [NotImplementedError] if called on the abstract class
+      # @raise [AbstractMethodError] if called on the abstract class
       def unparse hash
-        raise NotImplementedError
+        raise AbstractMethodError
       end
 
     end

data/lib/animoto/response_parsers/json_adapter.rb

@@ -6,7 +6,7 @@ module Animoto
       
       @format = 'json'
       
-      # @return [Hash<String,Object>]
+      # @return [Hash{String=>Object}]
       def parse string
         ::JSON.parse string
       end
@@ -15,8 +15,6 @@ module Animoto
       def unparse object
         ::JSON.unparse object
       end
-    end
-    
-    adapter_map.merge! :json => JSONAdapter
+    end    
   end
 end

data/lib/animoto/response_parsers/yajl_adapter.rb

@@ -6,7 +6,7 @@ module Animoto
       
       @format = 'json'
       
-      # @return [Hash<String,Object>]
+      # @return [Hash{String=>Object}]
       def parse string
         ::Yajl::Parser.parse string
       end
@@ -15,8 +15,6 @@ module Animoto
       def unparse object
         ::Yajl::Encoder.encode object
       end      
-    end
-    
-    adapter_map.merge! :yajl => YajlAdapter
+    end    
   end
 end

data/lib/animoto/support/content_type.rb

@@ -4,6 +4,7 @@ module Animoto
     
       # When included, includes the InstanceMethods module and extends the
       # ClassMethods module.
+      # @return [void]
       def self.included base
         base.class_eval {
           include Animoto::Support::ContentType::InstanceMethods