The gem for interacting with the API on Zencoder.
See http://zencoder.com/docs/api for more details on the API.
Tested on the following versions of Ruby:
- Ruby 1.8.6-p399
- Ruby 1.8.7-p174
- Ruby 1.9.1-p378
- Ruby 1.9.2-preview3
- Ruby Enterprise Edition 1.8.7-2010.02
- Rubinius 1.0.1-20100603
- jRuby 1.5.1
The first thing you'll need to interact with the Zencoder API is your API key. You can use your API key in one of three ways. The first and easiest is to set it and forget it on the Zencoder module like so:
Zencoder.api_key = 'abcd1234'
Alternatively, you can use an environment variable:
ENV['ZENCODER_API_KEY'] = 'abcd1234'
You can also pass your API key in every request, but who wants to do that?
All calls in the Zencoder library either raise Zencoder::HTTPError or return a Zencoder::Response.
A Zencoder::Response can be used as follows:
response = Zencoder::Job.list
response.success? # => true if the response code was 200 through 299
response.code # => 200
response.body # => the JSON-parsed body or raw body if unparseable
response.raw_body # => the body pre-JSON-parsing
response.raw_response # => the raw Net::HTTP or Typhoeus response (see below for how to use Typhoeus)
When sending API request parameters you can specify them as a non-string object, which we'll then serialize to JSON (by default):
Zencoder::Job.create({:input => 's3://bucket/key.mp4'})
Or you can specify them as a string, which we'll just pass along as the request body:
Zencoder::Job.create('{"input": "s3://bucket/key.mp4"}')
There's more you can do on jobs than anything else in the API. The following methods are available: list, create, details, progress, resubmit, cancel, delete.
The hash you pass to the create method should be encodable to the JSON you would pass to the Job creation API call on Zencoder. We'll auto-populate your API key if you've set it already.
Zencoder::Job.create({:input => 's3://bucket/key.mp4'})
Zencoder::Job.create({:input => 's3://bucket/key.mp4',
:outputs => [{:label => 'vp8 for the web',
:url => 's3://bucket/key_output.webm'}]})
Zencoder::Job.create({:input => 's3://bucket/key.mp4', :api_key => 'abcd1234'})
This returns a Zencoder::Response object. The body includes a Job ID, and one or more Output IDs (one for every output file created).
response = Zencoder::Job.create({:input => 's3://bucket/key.mp4'})
response.code # => 201
response.body['id'] # => 12345
By default the jobs listing is paginated with 50 jobs per page and sorted by ID in descending order. You can pass two parameters to control the paging: page and per_page.
Zencoder::Job.list
Zencoder::Job.list(:per_page => 10)
Zencoder::Job.list(:per_page => 10, :page => 2)
Zencoder::Job.list(:per_page => 10, :page => 2, :api_key => 'abcd1234')
The number passed to details is the ID of a Zencoder job.
Zencoder::Job.details(1)
Zencoder::Job.details(1, :api_key => 'abcd1234')
The number passed to resubmit is the ID of a Zencoder job.
Zencoder::Job.resubmit(1)
Zencoder::Job.resubmit(1, :api_key => 'abcd1234')
The number passed to cancel is the ID of a Zencoder job.
Zencoder::Job.cancel(1)
Zencoder::Job.cancel(1, :api_key => 'abcd1234')
The number passed to delete is the ID of a Zencoder job.
Zencoder::Job.delete(1)
Zencoder::Job.delete(1, :api_key => 'abcd1234')
Important: the number passed to progress is the output file ID, not the Job ID.
Zencoder::Output.progress(1)
Zencoder::Output.progress(1, :api_key => 'abcd1234')
By default the jobs listing is paginated with 50 jobs per page and sorted by ID in descending order. You can pass three parameters to control the paging: page, per_page, and since_id. Passing since_id will return notifications for jobs created after the job with the given ID.
Zencoder::Notification.list
Zencoder::Notification.list(:per_page => 10)
Zencoder::Notification.list(:per_page => 10, :page => 2)
Zencoder::Notification.list(:per_page => 10, :page => 2, :since_id => 20)
Zencoder::Notification.list(:api_key => 'abcd1234')
The hash you pass to the create method should be encodable to the JSON you would pass to the Account creation API call on Zencoder. No API key is required for this call, of course.
Zencoder::Account.create({:terms_of_service => 1,
:email => '[email protected]'})
Zencoder::Account.create({:terms_of_service => 1,
:email => '[email protected]',
:password => 'abcd1234',
:affiliate_code => 'abcd1234'})
Zencoder::Account.details
Zencoder::Account.details(:api_key => 'abcd1234')
This will put your account into integration mode (site-wide).
Zencoder::Account.integration
Zencoder::Account.integration(:api_key => 'abcd1234')
This will put your account into live mode (site-wide).
Zencoder::Account.live
Zencoder::Account.live(:api_key => 'abcd1234')
By default this library will use Net::HTTP to make all API calls. You can change the backend or add your own:
require 'typhoeus'
Zencoder::HTTP.http_backend = Zencoder::HTTP::Typhoeus
require 'my_favorite_http_library'
Zencoder::HTTP.http_backend = MyFavoriteHTTPBackend
See the HTTP backends in this library to get started on your own.
A secondary options hash can be passed to any method call which will then be passed on to the HTTP backend. You can pass timeout (in milliseconds), headers, and params (will be added to the query string) to any of the backends. If you are using Typhoeus, see their documentation for further options. In the following example the timeout is set to one second:
Zencoder::Job.create({:input => 's3://bucket/key.mp4'}, {:timeout => 1000})
By default we'll send and receive JSON for all our communication. If you would rather use XML then you can pass :format => :xml in the secondary options hash.
Zencoder::Job.create({:input => 's3://bucket/key.mp4'}, {:format => :xml})
We try to find the files necessary for SSL verification on your system, but sometimes this results in an error. If you'd like to skip SSL verification you can pass an option in the secondary options hash.
NOTE: WE HIGHLY DISCOURAGE THIS! THIS WILL LEAVE YOU VULNERABLE TO MAN-IN-THE-MIDDLE ATTACKS!
Zencoder::Job.create({:input => 's3://bucket/key.mp4'}, {:skip_ssl_verify => true})
Alternatively you can add it to the default options.
Zencoder::HTTP.default_options.merge!(:skip_ssl_verify => true)
Default options are passed to the HTTP backend. These can be retrieved and modified.
Zencoder::HTTP.default_options = {:timeout => 3000,
:headers => {'Accept' => 'application/json',
'Content-Type' => 'application/json'}}
The Net::HTTP backend will do its best to locate your local SSL certs to allow SSL verification. For a list of paths that are checked, see Zencoder::HTTP::NetHTTP.root_cert_paths. Feel free to add your own at runtime. Let us know if we're missing a common location.
Zencoder::HTTP::NetHTTP.root_cert_paths << '/my/custom/cert/path'
This library uses the activesupport gem to encode and decode JSON. The latest versions of ActiveSupport allow you to change the libraries used to decode JSON and XML.
You can change the JSON decoding backend for ActiveSupport in Rails 2.3 like so:
ActiveSupport::JSON.backend = "JSONGem"
Or change the XML decoding backend for ActiveSupport in Rails 2.3 like so:
ActiveSupport::XmlMini.backend = "Nokogiri"