An Elixir library for interacting with the Zencoder API.
Requires Elixir ~> 1.0.0
Install the Hex.pm package
-
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
-
Add
:zencoder
to your application dependencies:def application do [applications: [:zencoder]] end
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:
-
Set it from within your application
Zencoder.api_key "your-api-key"
-
Set it as the environment variable
ZENCODER_API_KEY
ZENCODER_API_KEY=your-api-key iex -S mix
-
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"})
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:
-
Set it from within your application
Zencoder.base_url "https://app.zencoder.com/api/v1"
-
Set it as the environment variable
ZENCODER_BASE_URL
ZENCODER_BASE_URL=https://app.zencoder.com/api/v1 iex -S mix
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:
-
Setting it from within your application
Zencoder.timeout 60000
-
Set it as the environment variable
ZENCODER_TIMEOUT
ZENCODER_TIMEOUT=60000 iex -S mix
-
Every request takes a map as its final argument, you may provide your custom timeout there
Zencoder.Job.progress(12345, %{timeout: 60000})
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.
A Zencoder response has the following fields:
- body: A Map containing the parsed body of the response, or an empty map if the response body could not be parsed
- success?: true or false depending on if the request was successful
- code: The HTTP status code of the response
- headers: The response headers
- raw_body: The raw string of the response body. (Likely JSON or an empty string)
- errors: An List of errors, or an empty List. This is a shortcut for
response.body[:errors]
A Zencoder error has the following fields:
- stacktrace: The formatted exception
- kind: The type of error
- 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.
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://app.zencoder.com/docs
%Zencoder.Error{} = response ->
# timed out? Zencoder broken? Computers are hard! Perhaps some nice retry logic.
# Check out our integration reliability guide:
# https://app.zencoder.com/docs/guides/advanced-integration/stable-integration
end
Create a new job.
# Basic job
Zencoder.Job.create(%{input: "http://s3.amazonaws.com/zencodertesting/test.mov"})
# More extensive job, see https://app.zencoder.com/docs/api/encoding 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)
Get details about an input.
Zencoder.Input.details(12345)
Get progress for an input.
Zencoder.Input.progress(12345)
Get details about an output.
Zencoder.Output.details(12345)
Get progress for an output.
Zencoder.Output.progress(12345)
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"}
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: "tedjones@example.com", terms_of_service: 1}
# Create an account with all possible options
Zencoder.Account.create %{
email: "tedjones2@example.com",
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