Panda Stream
Table of Contents
Panda is a powerful video encoding solution which makes it easy to add video uploading and encoding to your app.
We provide a jQuery uploader that you embed on a page in your application and sends the video directly to Panda, an encoder that converts it to any format you like, and a REST API to let you manage videos.
Prerequisites
Panda uses Amazon S3 buckets to store encoded videos. Before you can use the add-on, you’ll need your Amazon Access Key ID and Amazon Secret Key. You can find these in the Security Credentials section of your Amazon account. If you don’t have one, you can sign up for an S3 account.
This guide assumes that you’re using Rails, although Panda will still work with other Heroku-deployable applications.
Add the Heroku Add-on
The free plan allows you to upload and encode an unlimited number of videos. However the filesize of uploads must be less than 10Mb. For production usage there a several paid plans available with no upload limit and dedicated encoders.
To install the free version of the Panda add-on, simply run:
$ heroku addons:add pandastream
Adding pandastream:sandbox to myapp... done
You can also do this from the Resources section of your application’s configuration page on Heroku.
When you add your Heroku addon, It automatically creates a new Pandastream account which is only available from Heroku. You should not signup to the website directly.
Running this command will set the Heroku configuration variable PANDASTREAM_URL. You can see it by typing heroku config --long.
Install the Gem
Add the Panda gem to your Gemfile so that it will be loaded. (tip: on Bamboo stack you also need to fix the version of Typhoeus to 0.2.4)
gem 'typhoeus', '~> 0.2.4'
gem 'panda', '~> 1.5.0'
Next install it:
$ bundle install
Finally, create the file config/initializers/panda.rb with the line below so that your application connects to Panda when it starts:
Panda.configure(ENV['PANDASTREAM_URL'])
Configure Panda
Before using Panda in your application, you need to let Panda know where to save encoded videos.
$ heroku addons:open pandastream
Click on Settings and enter your S3 bucket and credentials.
Set Up Locally
ENV['PANDASTREAM_URL'] isn’t set locally by default. By copying the connection information to config/environments/development.rb you will be able to use your Heroku Panda account in development mode locally.
$ heroku config --long
PANDASTREAM_URL => http://a8704c6c854d69a031d8:efe2c61c3edfc7772556@api.pandastream.com:443/927a9d9xk37ded62422d4613229c156f
Copy the connection url to config/environments/development.rb:
$ ENV['PANDASTREAM_URL'] = "http://a8704c6c854d69a031d8:efe2c61c3edfc7772556@api.pandastream.com:443/927a9d9xk37ded62422d4613229c156f"
Test Your Setup
If you’ve set up your local development environment with your credentials, you can test on your local console by running script console.
Fire up a console:
$ heroku console
The initializer should connect you to Panda automatically, and you should be able to list all your encoding profiles.
>> Panda::Profile.all
=> [<Panda::Profile preset_name: h264, ...>]
You can now upload your videos to panda providing a source url or a local file. We have also made available a sample video for your convenience.
>> video = Panda::Video.create(:source_url => "http://panda-test-harness-videos.s3.amazonaws.com/panda.mp4")
or
>> video = Panda::Video.create(:file => " /local/path/panda.mp4")
Now wait until the video has finished encoding (which could be several minutes depending on the size). You can check by doing:
>> video.reload.status
=> "success"
Your input video has been uploaded to s3
>> video.encodings['h264'].reload
>> video.encodings['h264'].encoding_progress
=> 100
>> video.encodings['h264'].status
=> "success"
Now you can get the URL of a re-encoded version:
>> video.encodings['h264'].url
=> http://s3.amazonaws.com/S3_BUCKET/e40c1f68fbc1c4db46.mp4
Open this URL in your browser, and you’ll see that Panda has received, re-encoded, and stored your video into your S3 bucket.
Everything’s working nicely. Time to integrate with your application!
Integrating with Your App
Now you have successfully setup the Panda Heroku add-on, you’re ready to integrate Panda with your application. A step-by-step guide is available here: Integrating Panda with your Ruby on Rails application.
To learn more about what is possible with the Panda gem have a peek at the docs.
Panda encodes your videos to a standard MP4 (H264, AAC) profile by default, but you can set up Encoding Profiles to output whichever format you like through the web interface or the API.
The Panda gem handles the API interactions for you, but if you want to get closer to the metal, you can read the API documentation.