README.md in animoto-0.0.0.alpha1 vs README.md in animoto-0.0.0.alpha2

- old
+ new

@@ -1,39 +1,196 @@ -Animoto API Client -================== +Animoto API Ruby Client +======================= -## Workflow +The Animoto API is a RESTful web service that transforms images, videos, +music, and text into amazing video presentations. - require 'animoto/client' - include Animoto - - client = Client.new("username", "password") +The Animoto API Ruby Client provides a convenient Ruby interface for working +with the Animoto RESTful HTTP API. - 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") +### Topics - directing_job = client.direct!(manifest) - while directing_job.pending? - sleep(30) - client.reload!(directing_job) - end + * [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) - 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 +<a name="who_should_read_this_document"></a> +## Who should read this document? - if video = rendering_job.video - puts video.url - else - raise rendering_job.errors.first - end - else - raise directing_job.errors.first - end \ No newline at end of file +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