animoto 0.0.0.alpha0

data/README.md

@@ -0,0 +1,39 @@
+Animoto API Client
+==================
+
+## Workflow
+
+	require 'animoto/client'
+	include Animoto
+	
+	client = Client.new("username", "password")
+
+	manifest = DirectingManifest.new(:title => "Amazing Title!", :producer => "Fishy Joe")
+	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 << Song.new("http://website.com/song.mp3", :artist => "Fishy Joe")
+
+	directing_job = client.direct!(manifest)
+	while directing_job.pending?
+		sleep(30)
+		client.reload!(directing_job)
+	end
+
+	if storyboard = directing_job.storyboard
+		manifest = RenderingManifest.new(storyboard, :resolution => "720p", :framerate => 24, :format => 'h264')
+		rendering_job = client.render!(manifest)
+		while rendering_job.pending?
+			sleep(30)
+			client.reload!(rendering_job)
+		end
+
+		if video = rendering_job.video
+			puts video.url
+		else
+			raise rendering_job.errors.first
+		end
+	else
+		raise directing_job.errors.first
+	end

data/lib/animoto/asset.rb

@@ -0,0 +1,25 @@
+module Animoto
+  class Asset
+    
+    attr_accessor :source_url
+    
+    def initialize source_url, options = {}
+      @source_url = source_url
+    end
+    
+    # Returns a representation of this asset as a Hash. Used mainly for generating
+    # manifests.
+    #
+    # @return [Hash] this asset as a Hash
+    def to_hash
+      { 'source_url' => @source_url }
+    end
+    
+    # Returns a representation of this asset as JSON.
+    #
+    # @return [String] this asset as JSON
+    def to_json
+      self.to_hash.to_json
+    end
+  end
+end

data/lib/animoto/client.rb

@@ -0,0 +1,226 @@
+require 'uri'
+require 'net/http'
+require 'net/https'
+require 'json'
+require 'yaml'
+
+require 'animoto/errors'
+require 'animoto/content_type'
+require 'animoto/standard_envelope'
+require 'animoto/resource'
+require 'animoto/asset'
+require 'animoto/visual'
+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'
+
+module Animoto
+  class Client
+    API_ENDPOINT      = "http://api2-staging.animoto.com/"
+    API_VERSION       = 1
+    BASE_CONTENT_TYPE = "application/vnd.animoto"
+    HTTP_METHOD_MAP   = {
+      :get  => Net::HTTP::Get,
+      :post => Net::HTTP::Post
+    }
+    
+    attr_accessor :key, :secret
+    attr_reader   :format
+    
+    # Creates a new Client object which handles credentials, versioning, making requests, and
+    # parsing responses.
+    #
+    # If you have your key and secret in ~/.animotorc or /etc/.animotorc, those credentials will
+    # be read from those files (in that order) whenever you make a new Client if you don't specify
+    # them explicitly.
+    #
+    # @param [String] key the API key for your account
+    # @param [String] secret the secret key for your account
+    # @return [Client]
+    # @raise [ArgumentError] if no credentials are supplied
+    def initialize *args
+      @debug = ENV['DEBUG']
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      @key = args[0]
+      @secret = args[1]
+      unless @key && @secret
+        home_path = File.expand_path '~/.animotorc'
+        config = if File.exist?(home_path)
+          YAML.load(File.read(home_path))
+        elsif File.exist?('/etc/.animotorc')
+          YAML.load(File.read('/etc/.animotorc'))
+        end
+        if config
+          @key ||= config['key']
+          @secret ||= config['secret']
+        else
+          raise ArgumentError, "You must supply your key and secret"
+        end
+      end
+      @format = 'json'
+      uri = URI.parse(API_ENDPOINT)
+      @http = Net::HTTP.new uri.host, uri.port
+      # @http.use_ssl = true
+    end
+    
+    # Finds a resource by its URL.
+    #
+    # @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
+    def find klass, url, options = {}
+      klass.load(find_request(klass, url, options))
+    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
+    def direct! manifest, options = {}
+      DirectingJob.load(send_manifest(manifest, DirectingJob.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
+    def render! manifest, options = {}
+      RenderingJob.load(send_manifest(manifest, RenderingJob.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
+    def direct_and_render! manifest, options = {}
+      DirectingAndRenderingJob.load(send_manifest(manifest, DirectingAndRenderingJob.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
+    def reload! resource, options = {}
+      resource.load(find_request(resource.class, resource.url, options))
+    end
+    
+    private
+    
+    # Builds a request to find a resource.
+    #
+    # @param [Class] klass the Resource class you're looking for
+    # @param [String] url the URL of the resource
+    # @param [Hash] options
+    # @return [Hash] deserialized JSON response body
+    def find_request klass, url, options = {}
+      request(:get, URI.parse(url).path, nil, { "Accept" => content_type_of(klass) }, options)
+    end
+    
+    # Builds a request requiring a manifest.
+    #
+    # @param [Manifest] manifest the manifest being acted on
+    # @param [String] endpoint the endpoint to send the request to
+    # @param [Hash] options
+    # @return [Hash] deserialized JSON response body
+    def send_manifest manifest, endpoint, options = {}
+      request(:post, endpoint, manifest.to_json, { "Accept" => "application/#{format}", "Content-Type" => content_type_of(manifest) }, options)
+    end
+    
+    # Makes a request and parses the response.
+    #
+    # @param [Symbol] method which HTTP method to use (should be lowercase, i.e. :get instead of :GET)
+    # @param [String] uri the request path
+    # @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 JSON response body
+    def request method, uri, body, headers = {}, options = {}
+      req = build_request method, uri, body, headers, options
+      read_response @http.request(req)
+    end
+    
+    # Builds the request object.
+    #
+    # @param [Symbol] method which HTTP method to use (should be lowercase, i.e. :get instead of :GET)
+    # @param [String] uri the request path
+    # @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 [Net::HTTPRequest] the request object
+    def build_request method, uri, body, headers, options
+      req = HTTP_METHOD_MAP[method].new uri
+      req.body = body
+      req.initialize_http_header headers
+      req.basic_auth key, secret
+      req
+    end
+
+    # Verifies and parses the response.
+    #
+    # @param [Net::HTTPResponse] response the response object
+    # @return [Hash] deserialized JSON response body
+    def read_response response
+      check_status response
+      parse_response response
+    end
+    
+    # Checks the status of the response to make sure it's successful.
+    #
+    # @param [Net::HTTPResponse] response the response object
+    # @return [nil]
+    # @raise [Error,RuntimeError] if the response code isn't in the 200 range
+    def check_status response
+      unless (200..299).include?(response.code.to_i)
+        if response.body
+          begin
+            json = JSON.parse(response.body)
+            errors = json['response']['status']['errors']
+          rescue => e
+            raise response.message
+          else
+            raise Animoto::Error.new(errors.collect { |e| e['message'] }.join(', '))
+          end
+        else
+          raise response.message
+        end
+      end
+    end
+    
+    # Parses a JSON response body into a Hash.
+    # @param [Net::HTTPResponse] response the response object
+    # @return [Hash] deserialized JSON response body
+    def parse_response response
+      JSON.parse(response.body)
+    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
+    #   content type for
+    # @return [String] the full content type with the version and format included (i.e.
+    #   "application/vnd.animoto.storyboard-v1+json")
+    def content_type_of klass_or_instance
+      klass = klass_or_instance.is_a?(Class) ? klass_or_instance : klass_or_instance.class
+      "#{BASE_CONTENT_TYPE}.#{klass.content_type}-v#{API_VERSION}+#{format}"
+    end
+    
+  end
+end

data/lib/animoto/content_type.rb

@@ -0,0 +1,47 @@
+module Animoto
+  module ContentType
+    
+    # When included, includes the InstanceMethods module and extends the
+    # ClassMethods module.
+    def self.included base
+      base.class_eval {
+        include Animoto::ContentType::InstanceMethods
+        extend Animoto::ContentType::ClassMethods
+      }
+    end
+    
+    module InstanceMethods
+      # Returns the content type for this class.
+      #
+      # @return [String] the content type
+      def content_type
+        self.class.content_type
+      end
+    end
+    
+    module ClassMethods
+      # @overload content_type(type)
+      #   Sets the content type for this class.
+      #   @param [String] content_type the type
+      #   @return [String] the content type
+      # @overload content_type()
+      #   Returns the content type for this class.
+      #   @return [String] the content type
+      def content_type type = nil
+        @content_type = type if type
+        @content_type || infer_content_type
+      end
+      
+      private
+      
+      # If no content type is explicitly set, this will infer the name of the content
+      # type from the class name by lowercasing and underscoring the base name of the
+      # class. For example, Animoto::DirectingJob becomes "directing_job".
+      #
+      # @return [String] the inferred content type
+      def infer_content_type
+        name.split('::').last.gsub(/(^)?([A-Z])/) { "#{'_' unless $1}#{$2.downcase}" }
+      end      
+    end
+  end
+end

data/lib/animoto/directing_and_rendering_job.rb

@@ -0,0 +1,19 @@
+module Animoto
+  class DirectingAndRenderingJob < Animoto::Job
+    
+    endpoint '/jobs/directing_and_rendering'
+
+    def self.unpack_standard_envelope body
+      super.merge(:video_url => body['response']['payload'][payload_key]['links']['video'])
+    end
+    
+    attr_reader :video, :video_url
+    
+    def instantiate attributes = {}
+      @video_url = attributes[:video_url]
+      @video = Animoto::Video.new(:url => @video_url) if @video_url
+      super
+    end
+    
+  end
+end

data/lib/animoto/directing_and_rendering_manifest.rb

@@ -0,0 +1,25 @@
+module Animoto
+  class DirectingAndRenderingManifest < Animoto::DirectingManifest
+    
+    attr_accessor :resolution, :framerate, :format
+    
+    def initialize options = {}
+      super
+      @resolution = options[:resolution]
+      @framerate  = options[:framerate]
+      @format     = options[:format]
+    end
+    
+    def to_hash options = {}
+      hash  = super
+      directing_job = hash.delete('directing_job')
+      hash['directing_and_rendering_job'] = directing_job.merge('rendering_manifest' => { 'rendering_profile' => {}})
+      profile = hash['directing_and_rendering_job']['rendering_manifest']['rendering_profile']
+      profile['vertical_resolution'] = resolution
+      profile['framerate'] = framerate
+      profile['format'] = format
+      hash
+    end
+    
+  end
+end

data/lib/animoto/directing_job.rb

@@ -0,0 +1,18 @@
+module Animoto
+  class DirectingJob < Animoto::Job
+    
+    endpoint '/jobs/directing'
+
+    def self.unpack_standard_envelope body
+      super.merge(:storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'])
+    end
+    
+    attr_reader :storyboard, :storyboard_url
+
+    def instantiate attributes = {}
+      @storyboard_url = attributes[:storyboard_url]
+      @storyboard = Animoto::Storyboard.new(:url => @storyboard_url) if @storyboard_url
+      super
+    end
+  end
+end

data/lib/animoto/directing_manifest.rb

@@ -0,0 +1,115 @@
+module Animoto
+  class DirectingManifest < Animoto::Manifest
+
+    attr_accessor :title, :producer, :pacing, :http_callback_url, :http_callback_format
+    attr_reader   :visuals, :song, :style
+
+    # Creates a new DirectingManifest.
+    #
+    # @param [Hash] options
+    # @option options [String] :title the title of this project
+    # @option options [String] :producer the name of the producer of this project
+    # @option options ['default','half','double'] :pacing ('default') the pacing for this project
+    # @option options [String] :http_callback_url a URL to receive a callback when this job is done
+    # @option options ['json','xml'] :http_callback_format the format of the callback
+    def initialize options = {}
+      @title      = options[:title]
+      @producer   = options[:producer]
+      @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.
+    #
+    # @see TitleCard
+    # @return [TitleCard] the new TitleCard
+    def add_title_card *args
+      card = TitleCard.new *args
+      @visuals << card
+      card
+    end
+    
+    # Adds an Image to this manifest.
+    #
+    # @see Image
+    # @return [Image] the new Image
+    def add_image *args
+      image = Image.new *args
+      @visuals << image
+      image
+    end
+    
+    # Adds Footage to this manifest.
+    #
+    # @see Footage
+    # @return [Footage] the new Footage
+    def add_footage *args
+      footage = Footage.new *args
+      @visuals << footage
+      footage
+    end
+    
+    # Adds a Song to this manifest. Right now, a manifest can only have one song. Adding
+    # a second replaces the first.
+    #
+    # @see Song
+    # @return [Song] the new Song
+    def add_song *args
+      @song = Song.new *args
+    end
+
+    # Adds a visual/song to this manifest.
+    #
+    # @param [Visual,Song] asset the asset to add
+    # @raise [ArgumentError] if the asset isn't a Song or Visual
+    def add_visual asset
+      case asset
+      when Animoto::Song
+        @song = asset
+      when Animoto::Visual
+        @visuals << asset
+      else
+        raise ArgumentError
+      end      
+    end
+
+    # Adds a visual/song to this manifest.
+    #
+    # @param [Visual,Song] asset the asset to add
+    # @return [self]
+    def << asset
+      add_visual asset
+      self
+    end
+
+    # Returns a representation of this manifest as a Hash.
+    #
+    # @return [Hash] the manifest as a Hash
+    # @raise [ArgumentError] if a callback URL is specified but not the format
+    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
+      manifest = job['directing_manifest']
+      manifest['style'] = style
+      manifest['pacing'] = pacing if pacing
+      manifest['title'] = title if title
+      manifest['producer_name'] = producer if producer
+      manifest['visuals'] = []
+      visuals.each do |visual|
+        manifest['visuals'] << visual.to_hash
+      end
+      manifest['song'] = song.to_hash if song
+      hash
+    end
+    
+  end
+end

data/lib/animoto/errors.rb

@@ -0,0 +1,3 @@
+module Animoto
+  class Error < StandardError; end
+end

data/lib/animoto/footage.rb

@@ -0,0 +1,15 @@
+module Animoto
+  class Footage < Animoto::Asset
+    include Animoto::Visual
+    
+    attr_accessor :audio_mix, :start_time, :duration
+    
+    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

data/lib/animoto/image.rb

@@ -0,0 +1,14 @@
+module Animoto
+  class Image < Animoto::Asset
+    include Animoto::Visual
+
+    attr_accessor :rotation
+    
+    def to_hash
+      hash = super
+      hash['rotation'] = rotation if rotation
+      hash['spotlit'] = spotlit? unless @spotlit.nil?
+      hash
+    end
+  end
+end

data/lib/animoto/job.rb

@@ -0,0 +1,37 @@
+module Animoto
+  class Job < Animoto::Resource
+    
+    def self.unpack_standard_envelope body
+      super.merge(:state => body['response']['payload'][payload_key]['state'])
+    end
+        
+    attr_reader :url, :state, :errors
+    
+    # Returns true if the state of this job is 'failed'.
+    #
+    # @return [Boolean] whether or not the job has failed.
+    def failed?
+      @state == 'failed'
+    end
+    
+    # Returns true if the state of this job is 'completed'.
+    #
+    # @return [Boolean] whether or not the job is completed
+    def completed?
+      @state == 'completed'
+    end
+    
+    # Returns true if the job is neither failed or completed.
+    #
+    # @return [Boolean] whether or not the job is still pending
+    def pending?
+      !failed? && !completed?
+    end
+
+    def instantiate attributes = {}
+      @state  = attributes[:state]
+      super
+    end
+    
+  end
+end

data/lib/animoto/manifest.rb

@@ -0,0 +1,21 @@
+module Animoto
+  class Manifest
+    include ContentType
+    
+    # Returns a representation of this manifest as a Hash, used to populate
+    # request bodies when directing, rendering, etc.
+    #
+    # @return [Hash] the manifest as a Hash
+    def to_hash
+      {}
+    end
+    
+    # Returns a representation of this manifest as JSON.
+    #
+    # @return [String] the manifest as JSON
+    def to_json
+      self.to_hash.to_json
+    end
+    
+  end
+end

data/lib/animoto/rendering_job.rb

@@ -0,0 +1,24 @@
+module Animoto
+  class RenderingJob < Animoto::Job
+    
+    endpoint '/jobs/rendering'
+
+    def self.unpack_standard_envelope body
+      super.merge({
+        :storyboard_url => body['response']['payload'][payload_key]['links']['storyboard'],
+        :video_url      => body['response']['payload'][payload_key]['links']['video']
+      })
+    end
+    
+    attr_reader :storyboard, :storyboard_url, :video, :video_url
+    
+    def instantiate attributes = {}
+      @storyboard_url = attributes[:storyboard_url]
+      @storyboard = Animoto::Storyboard.new(:url => @storyboard_url) if @storyboard_url
+      @video_url = attributes[:video_url]
+      @video = Animoto::Video.new(:url => @video_url) if @video_url
+      super
+    end
+        
+  end
+end

data/lib/animoto/rendering_manifest.rb

@@ -0,0 +1,37 @@
+module Animoto
+  class RenderingManifest < Animoto::Manifest
+    
+    attr_accessor :storyboard, :resolution, :framerate, :format,
+      :http_callback_url, :http_callback_format
+      
+    def initialize storyboard, options = {}
+      @storyboard = storyboard
+      @resolution = options[:resolution]
+      @framerate  = options[:framerate]
+      @format     = options[:format]
+      @http_callback_url = options[:http_callback_url]
+      @http_callback_format = options[:http_callback_format]
+    end
+    
+    # Returns a representation of this manifest as a Hash.
+    #
+    # @return [Hash] 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_profile' => {} } } }
+      job   = hash['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
+      manifest = job['rendering_manifest']
+      manifest['storyboard_url'] = storyboard.url
+      profile = manifest['rendering_profile']
+      profile['vertical_resolution'] = resolution
+      profile['framerate'] = framerate
+      profile['format'] = format
+      hash
+    end    
+  end
+end