panda 0.6.4 → 1.0.0

data/Gemfile

@@ -0,0 +1,10 @@
+source :rubygems
+
+gem "ruby-hmac",">= 0.3.2"
+gem "rest-client"
+gem "json"
+
+gem "jeweler"
+gem "rake"
+gem "rspec"
+gem "webmock"

data/README.md

@@ -4,13 +4,394 @@ Panda gem provides an interface to access the [Panda](http://pandastream.com) AP
 
 ## Installation
 
-    sudo gem install panda -s http://gemcutter.org
+    gem install panda
 
 ## How to use it
 
     require 'rubygems'
     require 'panda'
 
+### Creating an instance of the client
+
+    Panda.configure do |config|
+      config.access_key = "panda_access_key"
+      config.secret_key = "panda_secret_key"
+      config.cloud_id = "panda_cloud_id"
+    end
+
+    or Panda.configure ({:access_key => ....})
+
+### Creating an instance of the client for EU
+
+    Panda.configure do |config|
+      config.access_key = "panda_access_key"
+      config.secret_key = "panda_secret_key"
+      config.cloud_id = "panda_cloud_id"
+      config.region = "eu"
+    end
+
+### Creating an instance using Heroku
+
+    Panda.configure do |config|
+      config.heroku = ENV['PANDASTREAM_URL']
+    end
+
+### Typical usage
+
+In most cases you will have used the [panda\_uploader](http://github.com/newbamboo/panda_uploader) jQuery plugin to upload the video (more details about this are in the [Integrating Panda with Ruby on Rails](http://pandastream.com/docs/integrate_with_rails) tutorial). Then you will want to get the video and screenshots urls of your encoding to display to your users.
+
+The name of the profile can be found in your [Panda account](http://pandastream.com/encoders) when editing an encoding cloud's profiles.
+
+    encodings = Panda::Video.find("1234").encodings
+    => [...]
+    
+    mp4_encoding = encodings.find_by_profile_name("h264")
+    ogg_encoding = encodings.find_by_profile_name("ogg")
+    
+    mp4_encoding.url
+    => "http://s3.amazonaws.com/my_panda_bucket/4567.mp4"
+
+    mp4_encoding.screenshots[4]
+    => "http://s3.amazonaws.com/my_panda_bucket/4567_4.jpg"
+    
+    ogg_encoding.url
+    => "http://s3.amazonaws.com/my_panda_bucket/9876.ogg"
+
+    ogg_encoding.screenshots[4]
+    => "http://s3.amazonaws.com/my_panda_bucket/9876_4.jpg"
+
+## Complete functionality
+
+###  Videos
+
+#### Find a video
+
+    video = Panda::Video.find("1234")
+    video.attributes
+    => {
+      "id"=>"1234",
+      "original_filename"=>"panda.mp4",
+      "source_url"=>"http://www.example.com/original_video.mp4",
+      "extname"=>".mp4",
+      "duration"=>14010,
+      "audio_codec"=>"aac",
+      "video_codec"=>"h264",
+      "file_size" => "44000",
+      "width"=>300,
+      "height"=>240,
+      "fps"=>29,
+      "status"=>"success",
+      "created_at"=>"2010/01/13 16:45:29 +0000",
+      "updated_at"=>"2010/01/13 16:45:35 +0000"
+    }
+
+    video.id
+    => "1234"
+    
+    video.created_at
+    =>"2010/01/13 16:45:29 +0000"
+    
+    video = Panda::Video.first
+    
+    video = Panda::Video.find("fake_id")
+    => raise: RecordNotFound: Couldn't find Video with ID=fake_id
+    
+    video.to_json
+    =>"{\"duration\":14010,\"created_at\":\"2010/01/13 16:45:29 +0000\",\"original_filename\":\"panda.mp4\"....}"
+
+    video.processing?
+    => false
+
+    video.fail?
+    => false
+
+    video.success?
+    => true
+    
+    video.reload
+    => <Panda::Video:0x1036fd660 ...>
+    
+##### Find encodings of a video
+    
+    video = Panda::Video.find("1234")
+    video.encodings
+    => [...]
+    
+    video.encodings.profile("3456")
+    => [...]
+    
+    or
+     
+    video.encodings.all(:profile_id => "3456")
+    => [...]
+    
+##### Find all videos
+
+    videos = Panda::Video.all
+    => [...]
+    
+    videos.first.id
+    => "3456"
+
+    videos = Panda::Video.page(2).per_page(20)
+    
+    or
+    
+    videos = Panda::Video.all(:page => 2, :per_page => 20)
+    videos.size
+    => 20
+
+##### Find all success videos
+
+    video = Panda::Video.status("success")
+    => [...]
+    
+    or
+    
+    videos = Panda::Video.all(:status => "success")
+    => [...]
+
+    status: success | processing | fail
+
+#### Create a new video
+
+  from a source
+    
+    video = Panda::Video.create(:source_url => "http://mywebsite.com/myvideo.mp4")
+    
+    or
+    
+    video = Panda::Video.new(:source_url => "http://mywebsite.com/myvideo.mp4")
+    video.create
+    => true
+    
+    # Note that you will need a movie file to test this. 
+    # You can grab http://panda-test-harness-videos.s3.amazonaws.com/panda.mp4
+    
+  from a local file
+    
+    video = Panda::Video.create(:file => File.new("/home/me/panda.mp4"))
+    
+    or
+    
+    video = Panda::Video.new(:file => File.new("/home/me/panda.mp4"))
+    video.create
+    => true
+
+#### Delete a video
+
+    Panda::Video.delete("1234")
+    
+    or
+  
+    video = Panda::Video.find("1234")
+    video.delete
+    => true
+    
+###  Encodings
+
+##### Find an encoding
+
+    encoding = Panda::Encoding.find("4567")
+    encoding.attributes
+    => {
+      "id"=>"4567",
+      "video_id"=>"1234",
+      "extname"=>".mp4",
+      "encoding_progress"=>60,
+      "encoding_time"=>3,
+      "file_size" => "25000",
+      "width"=>300,
+      "height"=>240,
+      "profile_id"=>"6789",
+      "status"=>"success",
+      "started_encoding_at"=>"2010/01/13 16:47:35 +0000",
+      "created_at"=>"2010/01/13 16:45:30 +0000",
+      "updated_at"=>"2010/01/13 16:47:40 +0000"
+    }
+    
+    encoding.encoding_progress
+    => 60
+
+    encoding.processing?
+    => false
+
+    encoding.fail?
+    => false
+
+    encoding.success?
+    => true
+    
+    encoding.video.original_filename
+    => "panda.mp4"
+    
+    encoding = Panda::Encoding.first
+    
+##### Find all encodings of a video
+
+    encodings = Panda::Encoding.page(4)
+    
+    or
+    
+    encodings = Panda::Encoding.all(:page => 4)
+    => [...]
+    
+    encodings = Panda::Encoding.video(video_id)
+    => [...]
+    
+    encoding = Panda::Encoding.video(video_id).profile_name("h264").first
+    
+    or
+    
+    encoding = Panda::Encoding.find_by :video_id => "video_id", :profile_name => "h264"
+    encoding.encoding_time
+    => 3
+    
+    profile = encodings.first.profile
+    profile.title
+    => "H264 profile"
+
+##### Find all success encodings
+
+    encodings = Panda::Encoding.video("1234").status("success")
+    or
+    encodings = Panda::Encoding.all(:video_id => "1234", :status => "success")
+    => [...]
+
+    or
+    
+    video = Panda::Video.find("1234")
+    video.encodings.status("success")
+
+    status: success | processing | fail
+    
+##### Retrieve the encoding 
+
+    encoding = Panda::Encoding.find("4567")
+    encoding.url
+    => "http://s3.amazonaws.com/my_panda_bucket/4567.mp4"
+
+    encoding.screenshots[0]
+    => "http://s3.amazonaws.com/my_panda_bucket/4567_1.jpg"
+
+##### Create a new encoding
+
+    encoding = Panda::Encoding.create(:video_id => 1234, :profile_id => 6789)
+    
+    or
+    
+    video = Panda::Video.find("123")
+    encoding = video.encodings.create(:profile => "profile_id")
+    
+##### Delete an encoding
+
+    Panda::Encoding.delete("4567")
+    
+    or
+    
+    encoding = Panda::Encoding.find("4567")
+    encoding.delete
+    => true
+    
+###  Profiles
+
+##### Find a profile
+
+    profile = Panda::Profile.find("6789")
+    
+##### Find all profiles
+
+    profiles = Panda::Profile.all
+
+##### Create a profile
+
+    profile = Panda::Profile.create(:preset_name => "h264")
+    profile = Panda::Profile.create(:command => "ffmpeg -i $input_file$ -y $output_file$", ....)
+
+##### Update a profile
+
+    profile = Panda::Profile.find("6789")
+    profile.width = 320
+    profile.height = 280
+    profile.save
+    => true
+    
+    profile.id = "fake_profile_id"
+    profile.save
+    => false
+    
+    profile.errors.last.to_s
+    => RecordNotFound: Couldn't find Profile with ID=fake_profile_id
+
+##### Delete a profile
+
+    Panda::Profile.delete("4567")
+
+    or
+
+    profile = Panda::Profile.find("6789")
+    profile.delete
+    => true
+
+##### All encoding of a profile
+
+    profile = Panda::Profile.find("6789")
+    profile.encodings
+    => [...]
+
+    profile.encodings.status("success")
+    or
+    profile.encodings.all(:status => "success")
+    => [...]
+    
+###  Using multiple clouds
+
+  By default Cloud.id uses options defined with: Panda.configure do .. end
+    
+    cloud_one = Panda::Cloud.find("cloud_id_1")
+    cloud_two = Panda::Cloud.find("cloud_id_2")
+  
+    cloud_one.profiles
+    cloud_two.profiles.find("profile_id")
+
+    cloud_two.videos
+    cloud_two.videos.status("success")
+    cloud_two.videos.all(:status => "success")
+    cloud_two.videos.all(:page => 2)
+
+    cloud_one.videos.find("video_id_1")
+    cloud_two.videos.find("video_id_2")
+    
+    cloud_two.profiles
+    cloud_two.profiles.create(:preset_name => "h264")
+    cloud_one.videos.create(:command => "ffmpeg -i $input_file$ -y $output_file$", ....)
+
+  You can also connect directly using Cloud.find
+    
+    cloud = Panda::Cloud.find("cloud_id_1", {:access_key => ..., :secret_key => ... })
+    
+
+## Generating signatures
+
+    All requests to your Panda cloud are signed using HMAC-SHA256, based on a timestamp and your Panda secret key. This is handled transparently. However, sometimes you will want to generate only this signature, in order to make a request by means other than this library. This is the case when using the [JavaScript panda_uploader](http://github.com/newbamboo/panda_uploader).
+
+    To do this, a method `signed_params()` is supported:
+
+        Panda.signed_params('POST', '/videos.json')
+        # => {'access_key' => '8df50af4-074f-11df-b278-1231350015b1',
+        # 'cloud_id' => 'your-cloud-id',
+        # 'signature' => 'LejCdm0O83+jk6/Q5SfGmk14WTO1pB6Sh6Z5eA2w5C0=',
+        # 'timestamp' => '2010-02-26T15:01:46.221513'}
+
+        Panda.signed_params('GET', '/videos.json', {'some_params' => 'some_value'})
+        # => {'access_key' => '8df50af4-074f-11df-b278-1231350015b1',
+        #  'cloud_id' => 'your-cloud-id',
+        #  'signature' => 'uHnGZ+kI9mT3C4vW71Iop9z2N7UKCv38v2l2dvREUIQ=',
+        #  'some_param' => 'some_value',
+        #  'timestamp' => '2010-02-26T15:04:27.039620'}
+
+## Old Panda way, still works
+
 ### Creating an instance of the client
     
     Panda.connect!({
@@ -77,7 +458,7 @@ Panda gem provides an interface to access the [Panda](http://pandastream.com) AP
       "profile_id"=>"00182830-0063-11df-8c8a-1231390041c1",
       "width"=>300}]
     
-### Deleting a video encoding
+### Deleting an encoding
 
     Panda.delete('/encodings/0f815986-0063-11df-a433-1231390041c1.json')
 
@@ -85,25 +466,6 @@ Panda gem provides an interface to access the [Panda](http://pandastream.com) AP
     
     Panda.delete('/videos/0ee6b656-0063-11df-a433-1231390041c1.json')
 
-## Generating signatures
-
-All requests to your Panda cloud are signed using HMAC-SHA256, based on a timestamp and your Panda secret key. This is handled transparently. However, sometimes you will want to generate only this signature, in order to make a request by means other than this library. This is the case when using the [JavaScript panda_uploader](http://github.com/newbamboo/panda_uploader).
-
-To do this, a method `signed_params()` is supported:
-
-    Panda.signed_params('POST', '/videos.json')
-    # => {'access_key' => '8df50af4-074f-11df-b278-1231350015b1',
-    # 'cloud_id' => 'your-cloud-id',
-    # 'signature' => 'LejCdm0O83+jk6/Q5SfGmk14WTO1pB6Sh6Z5eA2w5C0=',
-    # 'timestamp' => '2010-02-26T15:01:46.221513'}
-
-    Panda.signed_params('GET', '/videos.json', {'some_params' => 'some_value'})
-    # => {'access_key' => '8df50af4-074f-11df-b278-1231350015b1',
-    #  'cloud_id' => 'your-cloud-id',
-    #  'signature' => 'uHnGZ+kI9mT3C4vW71Iop9z2N7UKCv38v2l2dvREUIQ=',
-    #  'some_param' => 'some_value',
-    #  'timestamp' => '2010-02-26T15:04:27.039620'}
-
 ## Hash or JSON
 Since Panda 0.6, PandaGem returns a Hash by default. If you want PandaGem to return JSON do the following:
 
@@ -115,6 +477,11 @@ Since Panda 0.6, PandaGem returns a Hash by default. If you want PandaGem to ret
     })
 
 
+## Use bundler to setup the test environment (1.0)
+
+    bundler install
+    rake spec
+
 Copyright
 ---------