This add-on is operated by Brightcove

Quickly convert audio and video into web and mobile compatible formats.


Last Updated: 18 December 2013

encoding video zencoder

Table of Contents

Zencoder is an API-based online video encoding service. Zencoder converts videos from your website, application, or video library into formats that are compatible with web playback, mobile phone, or any other device you need to support.

Zencoder’s Video Encoding API allows you to seamlessly integrate your application with Zencoder’s extremely fast and scalable encoding platform. There are supported client libraries for Ruby and PHP, as well as third-party libraries for Java, Python, Node.js, Clojure.

Provisioning the add-on

Zencoder can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:add zencoder
-----> Adding zencoder to sharp-mountain-4005... done, v18 (free)

Once Zencoder has been added a ZENCODER_API_KEY setting will be available in the app configuration containing your new Zencoder API key. This can be confirmed using the heroku config:get command.

$ heroku config:get ZENCODER_API_KEY

After activating your Zencoder account, the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export ZENCODER_API_KEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the ZENCODER_API_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep ZENCODER_API_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Rails 3.x

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Zencoder client library.

gem 'zencoder'

Update application dependencies with bundler.

$ bundle install

Let’s create a new encoding job with one output that sends a notification to a URL you specify.

Both input and output url support any valid S3, Cloud Files, FTP, FTPS, SFTP, Aspera, or Syndication URL.

response = Zencoder::Job.create({
  :input => "http://example.com/files/key.mp4",
  :output => {
    :width => "480",
    :url => "s3://YOUR_S3_BUCKET/key_output.webm",
    :notification => "http://sharp-mountain-4005.herokuapp.com/zencoder/response"

response.success?     # => true
response.code         # => 200
response.body         # => { "id": "1234", "outputs": [{ "id": "4321" }] }

The request above will download key.mp4 and transcode it to WebM with a width of 480 (height will automatically be set to maintain aspect ratio). The encoded video will then be uploaded to the S3 bucket, “YOUR_S3_BUCKET” and a notification will be sent via a POST request to http://sharp-mountain-4005....

Make sure to update settings like input, url, and notification to fit your needs! Note the IDs in response.body above. 1234 is the job ID and 4321 is the output ID. Keep these in mind, they are used in the examples below.

If you’d like to see the progress of the whole job:

response = Zencoder::Job.progress(1234)

Remember that notification? Zencoder will send a POST request to the specified URL with a request body like this:


Get details about the job:

response = Zencoder::Job.details(1234)

Now that you’ve submitted some jobs, pull them back up:

response = Zencoder::Job.list
paginated = Zencoder::Job.list(:per_page => 10)
specific_page = Zencoder::Job.list(:per_page => 10, :page => 2)

Using with PHP

Before doing anything, you need to require the Zencoder PHP library.


Initialize the Services_Zencoder class with the ZENCODER_API_KEY environment variable.

$zencoder = new Services_Zencoder(getenv('ZENCODER_API_KEY'));

Create a new job

$encoding_job = $zencoder->jobs->create(array(
  "input" => "s3://bucket-name/file-name.avi",
  "outputs" => array(
      "label" => "web",
      "notification" => "http://sharp-mountain-4005.herokuapp.com/zencoder/response"

Consume the notification you just requested.

// Catch notification
$notification = $zencoder->notifications->parseIncoming();

// Check output/job state
if($notification->job->outputs[0]->state == "finished") {
  echo "w00t!\n";

  // If you're encoding to multiple outputs and only care when all of the outputs are finished
  // you can check if the entire job is finished.
  if($notification->job->state == "finished") {
    echo "Dubble w00t!";
} elseif ($notification->job->outputs[0]->state == "cancelled") {
  echo "Cancelled!\n";
} else {
  echo "Fail!\n";
  echo $notification->job->outputs[0]->error_message."\n";
  echo $notification->job->outputs[0]->error_link;

The 10,000 foot view

  • You have a video online that you need transcoded
  • Send API request to Zencoder with location of the file and desired outputs
  • Zencoder downloads the file via HTTP, FTP, SFTP, or from S3
  • Zencoder transcodes the file
  • Zencoder uploads the file to S3 or your FTP/SFTP server, or stores it for you for 24 hours on S3
  • Zencoder returns a HTTP request to your app with the job results

What should my request look like?

Unless you specify otherwise, an output is created with these defaults:

  • H.264 video, Baseline profile at the appropriate h264_level
  • AAC audio
  • Quality 3 (good compromise of visual quality and compression)
  • Same width/height as the original

This default will look pretty good, and will play in Flash, HTML5 (in Chrome and Safari), and on most mobile devices (as long as the resolution isn’t too high). If you need help deciding what outputs you need, please refer to Zencoder’s encoding recommendations.

You can fine-tune your outputs as much as you want using the full range of encoding settings available.


Plans purchased through Heroku have a hard usage limit, and if you reach that limit for the month you will start getting 401 errors on your job creation API requests. If your monthly needs are unpredictable or you expect overages, you may want to sign up directly through Zencoder where overages are charged according to your plan’s rate.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade zencoder:4k
-----> Upgrading zencoder:4k to sharp-mountain-4005... done, v18 ($120/mo)
       Your plan has been updated to: zencoder:4k

Removing the add-on

Zencoder can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:remove zencoder
-----> Removing zencoder from sharp-mountain-4005... done, v20 (free)


All Zencoder support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at help@zencoder.com.