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.
How it works
The Media APIs include a collection of APIs that follow a similar asynchronous processing pattern for cloud processing.
- Use your API token to authenticate
- Ensure your media is shared so as to be readable and writable by our services
- Make an asynchronous API call
Let's look at these steps.
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:
- Use your existing cloud storage such as AWS S3, Azure Blob Storage, or GCP Cloud Storage
- Use the Dolby.io Media Temporary Cloud Storage
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.
This approach has a few steps:
POSTto a media endpoint to start processing
GETto the same endpoint to check progress
- 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.
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.
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.
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.
|JSON||JSON data is returned in response to your ||Diagnose|
|Media File||A media file is written to the location specified as the output in the initial request.||Enhance|
|Data File||JSON data is written to the location specified as the output in the initial request.||Analyze|
Updated 11 days ago