Introduction to Media APIs

Overview of the Dolby.io Media APIs

Dolby.io Media APIs were created to make your audio better, at scale.

To deliver great audio, you need the tools and workflow automation to address your growing content libraries and meet consumer expectations. Whether your content is noisy, isn’t the right volume, or just doesn’t “feel right”, we’re here to help. Our cloud-based APIs analyze your audio, figure out how to optimally enhance it, and apply just the right amount of processing to give you a professional, natural sound.

Media APIs

How it works

The Media APIs include a collection of APIs that follow a similar asynchronous processing pattern for cloud processing.

  1. Use your API token to authenticate
  2. Ensure your media is shared so as to be readable and writable by our services
  3. Make an asynchronous API call

Let's look at these steps.

Authenticate

To use the Media APIs, you need to authorize your application's requests. To learn more about authentication, see our see API Authentication guide.

Process your media

To process your media, we need to be able to read and write it. There are a number of ways to achieve this:

See the Media Input and Output guide for examples of how to use these and Supported Media Formats for the types.

Make asynchronous requests

To process media, you first start a processing job and then need to wait for that processing job to complete. There are two approaches to handling this within your applications.

Polling

This approach has a few steps:

  1. POST to a media endpoint to start processing
  2. GET to the same endpoint to check progress
  3. Repeat step 2 until the job is complete

This is a common pattern called polling where GET requests are repeated while waiting on the returned status. The expected status values include:

  • Success - this status indicates the result is ready
  • Running - your media is being processed, check back again soon
  • Pending - your media is waiting for an available resource to run it
  • Cancelled - the job was terminated before it completed
  • Failed - there was a problem and you'll see an error with some additional notes about what the cause might be

You can run this as frequently as desired to check on the status of the job and inspect the progress value.

Webhooks

As an alternative to polling, you can receive a notification when a job is complete. This can be specified at the time of submission as a one-time callback or registered with the platform as a webhook to be fired for every job.

The Webhooks and Callbacks platform guide provides additional details about how to setup and receive these notifications.

Processing time

The more advanced algorithms used in some cases need some time to work their magic.

For example, in the case of the Media Enhance API the processing time may be more or less than the duration of the media itself depending on its length:

  • a 60 second input file may take 80 seconds to complete
  • a 5 minute input file may take 3 minutes and 30 seconds to complete

Our researchers are always working to make processing algorithms more efficient and decrease processing time overall. The Supported Media Formats provides a table of minimum and maximum file sizes that can be processed for each service.

Success

If all goes well you will get a status of Success.

You should check the API Reference for any services you intend to call to understand how results are returned. Depending on the API, you may get a JSON response or need to retrieve a media file or data file in a specified output location.

ResponseDescriptionExample API
JSONJSON data is returned in response to your GET request directly.Diagnose
Media FileA media file is written to the location specified as the output in the initial request.Enhance
Data FileJSON data is written to the location specified as the output in the initial request.Analyze