animoto 0.0.0.alpha1 → 0.0.0.alpha2

data/README.md

@@ -1,39 +1,196 @@
-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
+Animoto API Ruby Client
+=======================
+
+The Animoto API is a RESTful web service that transforms images, videos,
+music, and text into amazing video presentations.
+
+The Animoto API Ruby Client provides a convenient Ruby interface for working
+with the Animoto RESTful HTTP API.
+
+### Topics
+
+  * [Who should read this document](#who_should_read_this_document)
+  * [What is covered in this document](#what_is_covered_in_this_document)
+  * [Getting Started using the Ruby Client](#getting_started_using_the_ruby_client)
+  * [How to contribute to this client](#how_to_contribute)
+
+<a name="who_should_read_this_document"></a>
+## Who should read this document?
+
+This document is primarily aimed at developers looking to integrate with
+Animoto services from a Ruby environment or using the Ruby language.
+
+<a name="what_is_covered_in_this_document"></a>
+## What is covered in this document
+
+This document covers the technical details of the Animoto API Ruby client and 
+provides a general overview of its use.
+
+This document does not cover the details of the Animoto API itself. For such information please see the [Animoto API documentation][api_docs]
+
+<a name="getting_started_using_the_ruby_client"></a>
+## Getting Started using the Ruby Client
+
+### Prerequisites
+
+#### Readers of this document should be familiar with...
+
+  * The [the Ruby language](http://ruby-lang.org)
+  * The [Animoto API documentation][api_docs]
+
+#### Authentication
+
+You must have a application key and secret to use the Animoto API. If you
+don't have a key/secret pair, please contact your Animoto representative. Note
+that you may have multiple key/secret pairs at one time.
+
+### Conceptual overview of Animoto
+
+Creating a video using the Animoto API consists of two major steps:
+"directing" and "rendering".
+
+Directing is the process in which the Animoto system analyzes input visuals
+and music and determines the best way to present those visuals with the
+specified music. The output of directing is stored in the Animoto system for
+later use and is called a "storyboard".
+
+The second major phase of creating an Animoto video is called rendering.
+Rendering is the transformation of the artistic choices made by the director
+(and stored in a storyboard) into an actual video file that can be downloaded
+and viewed.
+
+Every time a new set of photos is to be transformed into a video, or every
+time a new set of artistic choices is to be made, a new storyboard must be
+created via directing. Once directing happens and a storyboard is created,
+videos can be rendered from that storyboard at any time, each with different
+resolutions, encodings, etc. suitable to different display environments.
+
+While directing and rendering are generally speedy processes, they do take
+longer than is appropriate for a typical HTTP request. These long-running
+tasks are represented as "jobs" in the Animoto API. Directing (creating
+storyboards) is accomplished by initiating a directing job, and rendering
+(creating a video file) starts by creating a rendering job. Jobs are a handy
+way to track status and debug problems if the requested operation couldn't be
+completed.
+
+### Creating a video using the Ruby client
+
+This example shows how to create an Animoto video in one shot with the Ruby
+client and using HTTP callbacks for status updates.
+
+    require 'animoto/client'
+    include Animoto
+
+    # Create a new client using our application key and secret
+    client = Client.new("application_key", "secret")
+
+    # create a directing and rendering manifest with the video title and 
+    # producer.  Also include rendering parameters like resolution, framerate,
+    # and format.
+    manifest = DirectingAndRenderingManifest.new(
+      :title => "Amazing Title!", 
+      :producer => "Fishy Joe", 
+      :resolution => "720p", 
+      :framerate => 24, 
+      :format => 'h264'
+    )
+    
+    # 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)
+    
+    # Setup the soundtrack.
+    manifest << Song.new("http://website.com/song.mp3", :artist => "Fishy Joe")
+    
+    # Setup to get http callbacks for status notification (see below for 
+    # polling example).
+    manifest.http_callback_url = "http://mysite.com/animoto_callback"
+    manifest.http_callback_format = "json"
+
+    # Send the manifest to the API.  Your app will be notified of 
+    # completion/failure via an HTTP POST to 
+    # "http://mysite.com/animoto_callback"
+    client.direct_and_render!(manifest)
+
+
+### A basic example using the Ruby client
+
+This example shows how to separately direct a storyboard and render a video
+with that storyboard. It also demonstrates how to use polling to check on job
+status.
+
+    require 'animoto/client'
+    include Animoto
+
+    # Create a new client using our application key and secret
+    client = Client.new("application_key", "secret")
+
+    # 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!", :producer => "Fishy Joe")
+    
+    # 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)
+    
+    # Setup the soundtrack.
+    manifest << Song.new("http://website.com/song.mp3", :artist => "Fishy Joe")
+
+    # Request a new directing job by sending the API our directing manifest.
+    directing_job = client.direct!(manifest)
+    
+    # Poll the service until the directing job is done.
+    while directing_job.pending?
+    	sleep(30)
+    	client.reload!(directing_job)
+    end
+
+    # If the directing job finished successfully, there will be a "storyboard" 
+    # associated with this job.
+    if storyboard = directing_job.storyboard
+    
+      # 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')
+    	
+    	# 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.
+    		puts video.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
+    end
+
+<a name="how_to_contribute"></a>
+## How to contribute to this client
+
+1. [Fork](http://help.github.com/forking/) `animoto_ruby_client`
+2. Create a topic branch - `git checkout -b my_branch`
+3. Push to your branch - `git push origin my_branch`
+4. Create an [Issue](http://github.com/animoto/animoto_ruby_client/issues) with a link to your branch
+5. That's it!
+
+You might want to checkout our [the wiki page](http://wiki.github.com/animoto/animoto_ruby_client) for information
+on coding standards, new features, etc.
+
+
+[api_docs]: http://animoto.com/developer/api

data/lib/animoto/asset.rb

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

data/lib/animoto/client.rb

@@ -10,6 +10,7 @@ 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'

data/lib/animoto/coverable.rb

@@ -0,0 +1,29 @@
+module Animoto
+  module Coverable
+    
+    # Setter for cover, which makes this visual the cover for the video. Only
+    # one image or piece of footage in a manifest can be declared the cover.
+    #
+    # @param [Boolean] bool true if this visual should be the cover
+    def cover= bool
+      @cover = bool
+    end
+    
+    # Returns true if this visual is the cover.
+    #
+    # @return [Boolean] whether or not this visual is the cover
+    def cover?
+      @cover
+    end
+    
+    # Returns a representation of this visual as a Hash.
+    #
+    # @return [Hash] this visual as a Hash
+    def to_hash
+      hash = super rescue {}
+      hash['cover'] = cover? unless @cover.nil?
+      hash
+    end
+    
+  end
+end

data/lib/animoto/directing_manifest.rb

@@ -1,20 +1,18 @@
 module Animoto
   class DirectingManifest < Animoto::Manifest
 
-    attr_accessor :title, :producer, :pacing, :http_callback_url, :http_callback_format
+    attr_accessor :title, :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    = []
@@ -102,7 +100,6 @@ module Animoto
       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

data/lib/animoto/footage.rb

@@ -1,6 +1,7 @@
 module Animoto
   class Footage < Animoto::Asset
     include Animoto::Visual
+    include Animoto::Coverable
     
     attr_accessor :audio_mix, :start_time, :duration
     
@@ -9,7 +10,7 @@ module Animoto
       hash['audio_mix'] = 'MIX' if audio_mix
       hash['start_time'] = start_time if start_time
       hash['duration'] = duration if duration
-      hash
+      hash 
     end
   end
 end

data/lib/animoto/image.rb

@@ -1,6 +1,7 @@
 module Animoto
   class Image < Animoto::Asset
     include Animoto::Visual
+    include Animoto::Coverable
 
     attr_accessor :rotation
     
@@ -8,6 +9,7 @@ module Animoto
       hash = super
       hash['rotation'] = rotation if rotation
       hash['spotlit'] = spotlit? unless @spotlit.nil?
+      hash['cover'] = cover? unless @cover.nil?
       hash
     end
   end

data/lib/animoto/rendering_manifest.rb

@@ -18,7 +18,7 @@ module Animoto
     # @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' => {} } } }
+      hash  = { 'rendering_job' => { 'rendering_manifest' => { 'rendering_parameters' => {} } } }
       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?
@@ -27,10 +27,10 @@ module Animoto
       end
       manifest = job['rendering_manifest']
       manifest['storyboard_url'] = storyboard.url
-      profile = manifest['rendering_profile']
-      profile['vertical_resolution'] = resolution
-      profile['framerate'] = framerate
-      profile['format'] = format
+      params = manifest['rendering_parameters']
+      params['resolution'] = resolution
+      params['framerate'] = framerate
+      params['format'] = format
       hash
     end    
   end

data/lib/animoto/song.rb

@@ -1,14 +1,12 @@
 module Animoto
   class Song < Animoto::Asset
     
-    attr_accessor :start_time, :duration, :title, :artist
+    attr_accessor :start_time, :duration
     
     def to_hash
       hash = super
       hash['start_time'] = start_time if start_time
       hash['duration'] = duration if duration
-      hash['title'] = title if title
-      hash['artist'] = artist if artist
       hash
     end
     

data/lib/animoto/video.rb

@@ -3,7 +3,7 @@ module Animoto
     
     def self.unpack_standard_envelope body
       super.merge({
-        :download_url => body['response']['payload'][payload_key]['links']['download'],
+        :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'],

data/lib/animoto.rb

@@ -1,5 +1,5 @@
 module Animoto
   def self.version
-    "0.0.0.alpha1"
+    "0.0.0.alpha2"
   end
 end

data/spec/animoto/asset_spec.rb

@@ -1 +1,5 @@
 require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::Asset do
+  
+end

data/spec/animoto/coverable_spec.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::Coverable do
+  
+end

data/spec/animoto/directing_and_rendering_manifest_spec.rb

@@ -8,7 +8,7 @@ describe Animoto::DirectingAndRenderingManifest do
   
   describe "generating a hash" do
     before do
-      manifest(:title => 'Funderful Wonderment', :producer => 'Senor Spielbergo', :pacing => 'double',
+      manifest(:title => 'Funderful Wonderment', :pacing => 'double',
         :resolution => "720p", :framerate => 24, :format => 'flv')
       @image = manifest.add_image 'http://website.com/image.png'
       @title_card = manifest.add_title_card 'woohoo', 'this is awesome'
@@ -69,11 +69,6 @@ describe Animoto::DirectingAndRenderingManifest do
         @hash['pacing'].should == manifest.pacing
       end
     
-      it "should have a 'producer_name' key in the manifest" do
-        @hash.should have_key('producer_name')
-        @hash['producer_name'].should == manifest.producer
-      end
-    
       it "should have a 'visuals' key in the manifest" do
         @hash.should have_key('visuals')
       end

data/spec/animoto/directing_manifest_spec.rb

@@ -23,14 +23,6 @@ describe Animoto::DirectingManifest do
       manifest.style.should == 'original'
     end
     
-    it "should default to no producer" do
-      manifest.producer.should be_nil
-    end
-    
-    it "should be able to specify the producer with a :producer parameter" do
-      manifest(:producer => "Senor Spielbergo").producer.should == "Senor Spielbergo"
-    end
-    
     it "should default to having to visuals" do
       manifest.visuals.should be_empty
     end
@@ -92,7 +84,7 @@ describe Animoto::DirectingManifest do
   
   describe "generating a hash" do
     before do
-      manifest(:title => 'Funderful Wonderment', :producer => 'Senor Spielbergo', :pacing => 'double')
+      manifest(:title => 'Funderful Wonderment', :pacing => 'double')
       @image = manifest.add_image 'http://website.com/image.png'
       @title_card = manifest.add_title_card 'woohoo', 'this is awesome'
       @footage = manifest.add_footage 'http://website.com/movie.mp4'
@@ -119,11 +111,6 @@ describe Animoto::DirectingManifest do
       manifest.to_hash['directing_job']['directing_manifest']['pacing'].should == manifest.pacing
     end
     
-    it "should have a 'producer_name' key in the manifest" do
-      manifest.to_hash['directing_job']['directing_manifest'].should have_key('producer_name')
-      manifest.to_hash['directing_job']['directing_manifest']['producer_name'].should == manifest.producer
-    end
-    
     it "should have a 'visuals' key in the manifest" do
       manifest.to_hash['directing_job']['directing_manifest'].should have_key('visuals')
     end

data/spec/animoto/footage_spec.rb

@@ -11,9 +11,9 @@ describe Animoto::Footage do
       @footage = Animoto::Footage.new 'http://website.com/movie.mp4'
     end
     
-    it "should have a 'source_url' key with the url" do
-      @footage.to_hash.should have_key('source_url')
-      @footage.to_hash['source_url'].should == @footage.source_url
+    it "should have a 'source' key with the url" do
+      @footage.to_hash.should have_key('source')
+      @footage.to_hash['source'].should == @footage.source
     end
     
     it "should not have a 'spotlit' key" do

data/spec/animoto/image_spec.rb

@@ -11,9 +11,9 @@ describe Animoto::Image do
       @image = Animoto::Image.new 'http://website.com/image.png'
     end
     
-    it "should have a 'source_url' key with the url" do
-      @image.to_hash.should have_key('source_url')
-      @image.to_hash['source_url'].should == @image.source_url
+    it "should have a 'source' key with the url" do
+      @image.to_hash.should have_key('source')
+      @image.to_hash['source'].should == @image.source
     end
     
     describe "if rotated" do

data/spec/animoto/rendering_manifest_spec.rb

@@ -61,18 +61,18 @@ describe Animoto::RenderingManifest do
       manifest.to_hash['rendering_job']['rendering_manifest']['storyboard_url'].should == @storyboard.url
     end
     
-    it "should have a 'rendering_profile' object in the manifest" do
-      manifest.to_hash['rendering_job']['rendering_manifest'].should have_key('rendering_profile')
-      manifest.to_hash['rendering_job']['rendering_manifest']['rendering_profile'].should be_a(Hash)
+    it "should have a 'rendering_parameters' object in the manifest" do
+      manifest.to_hash['rendering_job']['rendering_manifest'].should have_key('rendering_parameters')
+      manifest.to_hash['rendering_job']['rendering_manifest']['rendering_parameters'].should be_a(Hash)
     end
     
-    describe "rendering profile" do
+    describe "rendering parameters" do
       before do
-        @profile = manifest.to_hash['rendering_job']['rendering_manifest']['rendering_profile']
+        @profile = manifest.to_hash['rendering_job']['rendering_manifest']['rendering_parameters']
       end
       
-      it "should have a 'vertical_resolution' key" do
-        @profile['vertical_resolution'].should == manifest.resolution
+      it "should have a 'resolution' key" do
+        @profile['resolution'].should == manifest.resolution
       end
       
       it "should have a 'framerate' key" do

data/spec/animoto/song_spec.rb

@@ -7,9 +7,9 @@ describe Animoto::Song do
       @song = Animoto::Song.new 'http://website.com/song.mp3'
     end
     
-    it "should have a 'source_url' key with the url" do
-      @song.to_hash.should have_key('source_url')
-      @song.to_hash['source_url'].should == @song.source_url
+    it "should have a 'source' key with the url" do
+      @song.to_hash.should have_key('source')
+      @song.to_hash['source'].should == @song.source
     end
     
     describe "if a start time was specified" do
@@ -32,23 +32,6 @@ describe Animoto::Song do
         @song.to_hash.should have_key('duration')
         @song.to_hash['duration'].should == @song.duration
       end
-    end
-    
-    describe "if a title and/or artist was specified" do
-      before do
-        @song.title = "Antarctican Drinking Song"
-        @song.artist = "Gwar"
-      end
-      
-      it "should have an 'artist' key with the artist" do
-        @song.to_hash.should have_key('artist')
-        @song.to_hash['artist'].should == @song.artist
-      end
-      
-      it "should have a 'title' key with the title" do
-        @song.to_hash.should have_key('title')
-        @song.to_hash['title'].should == @song.title
-      end
-    end
+    end    
   end
 end

data/spec/animoto/standard_envelope_spec.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::StandardEnvelope do
+  
+end

data/spec/animoto/video_spec.rb

@@ -1 +1,5 @@
 require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::Video do
+  
+end

data/spec/animoto/visual_spec.rb

@@ -0,0 +1,5 @@
+require File.expand_path(File.dirname(__FILE__) + "/../spec_helper")
+
+describe Animoto::Visual do
+  
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: animoto
 version: !ruby/object:Gem::Version 
-  hash: -1710980557
+  hash: -1710980560
   prerelease: true
   segments: 
   - 0
   - 0
   - 0
-  - alpha1
-  version: 0.0.0.alpha1
+  - alpha2
+  version: 0.0.0.alpha2
 platform: ruby
 authors: 
 - Animoto
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-13 00:00:00 -04:00
+date: 2010-08-30 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -48,6 +48,7 @@ files:
 - ./lib/animoto/asset.rb
 - ./lib/animoto/client.rb
 - ./lib/animoto/content_type.rb
+- ./lib/animoto/coverable.rb
 - ./lib/animoto/directing_and_rendering_job.rb
 - ./lib/animoto/directing_and_rendering_manifest.rb
 - ./lib/animoto/directing_job.rb
@@ -69,6 +70,7 @@ files:
 - ./lib/animoto.rb
 - ./spec/animoto/asset_spec.rb
 - ./spec/animoto/client_spec.rb
+- ./spec/animoto/coverable_spec.rb
 - ./spec/animoto/directing_and_rendering_job_spec.rb
 - ./spec/animoto/directing_and_rendering_manifest_spec.rb
 - ./spec/animoto/directing_job_spec.rb