Skip to content

Latest commit

 

History

History
299 lines (214 loc) · 10.6 KB

README.md

File metadata and controls

299 lines (214 loc) · 10.6 KB
Raw

Zencoder

Build Status Coverage Status

An Elixir library for interacting with the Zencoder API.

Requires Elixir ~> 1.0.0

Installation

Install the Hex.pm package

  1. Add zencoder and ibrowse to your mix.exs dependencies:

    def deps do
  [
    {:zencoder, "~> 1.0.1"},
    {:ibrowse, github: "cmullaparthi/ibrowse", tag: "v4.1.0"},
  ]
end

  2. Add :zencoder to your application dependencies:

    def application do
  [applications: [:zencoder]]
end

API Key

To communicate with the Zencoder API you'll need to provide your API key, you can find your API key by logging into your Zencoder account and visiting https://app.zencoder.com/api

There are three ways to provide your API key to the Elixir library:

  1. Set it from within your application

    Zencoder.api_key "your-api-key"

  2. Set it as the environment variable ZENCODER_API_KEY

    ZENCODER_API_KEY=your-api-key iex -S mix

  3. Every request takes a map as its final argument, you may provide your API key there

    Zencoder.Job.progress(12345, %{api_key: "your-api-key"})

Base URL

By default the integration library will send all requests to version 2 of our API: "https://app.zencoder.com/api/v2". If, for whatever reason, you want to send requests to a different url you may configure your base URL in two ways:

  1. Set it from within your application

    Zencoder.base_url "https://app.zencoder.com/api/v1"

  2. Set it as the environment variable ZENCODER_BASE_URL

    ZENCODER_BASE_URL=https://app.zencoder.com/api/v1 iex -S mix

Timeout

We recommend wrapping your requests to Zencoder in a 30 second timeout. Zencoder usually responds in less than a second, so 30 seconds should give it plenty of time to respond. If the timeout is exceeded your request will return a %Zencoder.Error{} struct. If you wish to customize the length of the timeout you can do so by setting the timeout (in milliseconds) in three ways:

  1. Setting it from within your application

    Zencoder.timeout 60000

  2. Set it as the environment variable ZENCODER_TIMEOUT

    ZENCODER_TIMEOUT=60000 iex -S mix

  3. Every request takes a map as its final argument, you may provide your custom timeout there

    Zencoder.Job.progress(12345, %{timeout: 60000})

Responses

All API request functions will return either a %Zencoder.Response{} struct (which may or may not be successful) or a %Zencoder.Error{} struct if an exception occurred.

%Zencoder.Response{}

A Zencoder response has the following fields:

  1. body: A Map containing the parsed body of the response, or an empty map if the response body could not be parsed
  2. success?: true or false depending on if the request was successful
  3. code: The HTTP status code of the response
  4. headers: The response headers
  5. raw_body: The raw string of the response body. (Likely JSON or an empty string)
  6. errors: An List of errors, or an empty List. This is a shortcut for response.body[:errors]

%Zencoder.Error{}

A Zencoder error has the following fields:

  1. stacktrace: The formatted exception
  2. kind: The type of error
  3. error: The exception

Stacktrace is the formatted exception (via Exception.format/2). The kind and error are provided if you wish to do your own formatting.

Pattern Matching

You can pattern match to determine how to handle the response:

case Zencoder.Job.create %{test: true, input: "http://s3.amazonaws.com/zencodertesting/test.mov"} do
  %Zencoder.Response{success?: true} = response ->
    # some happy path stuff here
  %Zencoder.Response{success?: false} = response ->
    # uh oh, maybe something is wrong with your request?
    # better check the docs at https://support.brightcove.com/zencoder
  %Zencoder.Error{} = response ->
    # timed out? Zencoder broken? Computers are hard! Perhaps some nice retry logic.
    # Check out our integration reliability guide:
    # https://support.brightcove.com/zencoder-100-integration-reliability
end

Jobs

Create a new job.

# Basic job
Zencoder.Job.create(%{input: "http://s3.amazonaws.com/zencodertesting/test.mov"})

# More extensive job, see https://support.brightcove.com/zencoder-encoding-settings for more encoding settings
Zencoder.Job.create(%{
  input: "s3://zencodertesting/test.mov",
  outputs: [
    %{
      label: "mp4 high",
      url: "s3://your-bucket/output-file-name.mp4",
      h264_profile: "high"
    },
    %{
      url: "s3://your-bucket/output-file-name.webm",
      label: "webm",
      format: "webm"
    },
    %{
      url: "s3://your-bucket/output-file-name.ogg",
      label: "ogg",
      format: "ogg"
    },
    %{
      url: "s3://your-bucket/output-file-name-mobile.mp4",
      label: "mp4 low",
      size: "640x480"
    }
  ]
})

Get details about a job.

Zencoder.Job.details(12345)

Get progress on a job.

Zencoder.Job.progress(12345)

List jobs. By default this returns the last 50 jobs, but this can be altered in an optional Map.

Zencoder.Job.list(%{page: 1, per_page: 5, state: "finished"})

Cancel a job

Zencoder.Job.cancel(12345)

Resubmit a job

Zencoder.Job.resubmit(12345)

Inputs

Get details about an input.

Zencoder.Input.details(12345)

Get progress for an input.

Zencoder.Input.progress(12345)

Outputs

Get details about an output.

Zencoder.Output.details(12345)

Get progress for an output.

Zencoder.Output.progress(12345)

Reports

Reports are great for getting usage data for your account. All default to 30 days from yesterday with no grouping, but this can be altered in the optional Map. These will return 422 Unprocessable Entity if the date format is incorrect or the range is greater than 2 months. Correct date format is YYYY-MM-DD.

Get all usage (Live + VOD).

Zencoder.Report.all

# For a specific date range
Zencoder.Report.all %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping
Zencoder.Report.all %{grouping: "aperture-testing"}

Get VOD usage.

Zencoder.Report.vod

# For a specific date range
Zencoder.Report.vod %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping
Zencoder.Report.vod %{grouping: "aperture-testing"}

Get Live usage.

Zencoder.Report.live

# For a specific date range
Zencoder.Report.live %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping
Zencoder.Report.live %{grouping: "aperture-testing"}

Accounts

Create a new account. A unique email address and terms of service are required, but you can also specify a password (and confirmation) along with whether or not you want to subscribe to the Zencoder newsletter. New accounts will be created under the Test (Free) plan.

Zencoder.Account.create %{email: "[email protected]", terms_of_service: 1}

# Create an account with all possible options
Zencoder.Account.create %{
  email: "[email protected]",
  terms_of_service: 1,
  password: "sureamgladforssl",
  password_confirmation: "sureamgladforssl",
  newsletter: 0
}

Get details about the current account.

Zencoder.Account.details

Turn integration mode on (all jobs are test jobs).

Zencoder.Account.integration

Turn off integration mode, which means your account is live (and you'll be billed for jobs).

Zencoder.Account.live