Enhancing Media

The Dolby Enhance API is designed to improve the sound of your media. By analyzing your media and making changes with little effort you can automate tasks like reducing static environmental noises, dynamic volume control for more consistency, equalization and tonal balance management, and loudness correction and optimization. Using this API you can build a range of applications that deliver good quality media.

To get started without writing any code, you can use the Try It Yourself demo to upload a file and download the enhanced result. If you are ready for the next step to enhance your media files with a deeper integration you'll need to complete a few steps as outlined here:

  1. Get your API key
  2. Upload media
  3. Make an Enhance request
  4. Check the results
  5. Download media
  6. Learn more

This enhance is useful for applications such as delivering podcasts, online learning platforms, healthcare conferencing, or video sharing.

1. Get Your API Key

To use the Enhance API you need an API key. You can retrieve your API key once you create an account.

2. Upload Media

The Media Input and Output tutorial explains the various ways of making your media accessible. This includes options like pre-signed urls for AWS S3 or GCP, basic authentication, token authentication, etc.

There you'll also discover that we've provided a /media/input service for a quick solution to securely store media temporarily. Any media you upload will be removed regularly so shouldn't be used for permanent storage.

This is done in two steps.

First, call /media/input and identify a shortcut url. It must begin with dlb:// but everything after is up to you. You should replace $DOLBYIO_API_KEY with your own key or set an environment variable appropriate for your system.

curl -X POST https://api.dolby.com/media/input \
  --header "x-api-key: $DOLBYIO_API_KEY" \
  --data '{
      "url": "dlb://in/example.mp3"
  }'

The response will return JSON data with a pre-signed url for a cloud storage location. You need to upload your file to this pre-signed url. You do this with a PUT call for that url endpoint. You should replace $PRE_SIGNED_URL with the value returned from the call to /media/input.

curl -X PUT $PRE_SIGNED_URL -T ./your-local-media.mp3

Once the upload is complete, you'll be able to refer to this media with the dlb://in/example.mp3 shortcut. See the Media Input and Output tutorial for a more detailed explanation.

3. Make an Enhance Request

The Enhance API requires an input and an output parameter to begin enhancing your media. You'll use the dlb:// url shortcut from the previous step as your input. You can also identify a dlb:// url for the output and the API will create that location and store the result.

Depending on the duration of your media it can take some time to fully enhance the audio so this service runs asynchronously. Replace $DOLBYIO_API_KEY with your own or use an environment variable to begin processing.

curl -X POST https://api.dolby.com/media/enhance \
     --header "x-api-key: $DOLBYIO_API_KEY" \
     --data '{
         "input": "dlb://in/example.mp3",
         "output": "dlb://out/example-enhanced.mp3"
     }'

The JSON response will include a unique job_id that you'll need to check results.

{"job_id":"b49955b4-9b64-4d8b-a4c6-2e3550472a33"}

4. Check the Results

During enhancement, your job will go through a few steps such as Pending, Running, and finally Success when complete. You may need to make this GET request multiple times until processing is finished.

Review the Introduction for recommendations on polling for status, progress, and processing times.

Replace $DOLBYIO_API_KEY with your own or use an environment variable. You also should replace $DOLBYIO_JOB_ID with the value returned from the previous step.

curl -X GET "https://api.dolby.com/media/enhance?job_id=$DOLBYIO_JOB_ID" \
     --header "x-api-key: $DOLBYIO_API_KEY"

While the job is still in progress, you will be able to see the status and progress values returned.

{
  "path": "/media/enhance",
  "status": "Running",
  "progress": 0
}

If you re-run and call again after a period of time you'll see the status changes and the output you originally specified will be ready for downloading.

{
  "path": "/media/enhance",
  "progress": 100,
  "result": {},
  "status": "Success"
}

5. Download Media

You can now retrieve your enhanced output media using /media/output. This service takes a dlb:// shortcut url as input and will start downloading your results.

curl  -X GET https://api.dolby.com/media/output?url=dlb://out/example-enhanced.mp3
      -O -L
      --header "x-api-key: $DOLBYIO_API_KEY"

You specify the -L because the service will redirect you to a cloud storage location. You shouldn't try to retrieve directly from the cloud storage as the location may change, so use /media/output with the shortcut instead. The -O is to just output the file to your local system with the same filename.

Take a listen to the enhanced media.

Learn More

That's just the start of what you can do with the Enhance API. For more information, these resources may be helpful: