The Dolby.io Audio Diagnose API is designed to help you understand your media and detect problems. It provides:

Overall audio quality scores
Information about specific problems such as speech sibilance events and silent channels
Summary information about the content such as percentages of speech and music

⚠
️ Not a Developer?
To get started without writing any code, you can use the Media API Demo demo to upload a file and view the results.

Getting started

To get started you'll follow these steps.

Get your API token
Prepare your media
Make a Diagnose request
Check the results

1. Get your API token

To use the Audio Diagnose API, you need an API token. To learn more about how to get an API token, see API Authentication.

2. Prepare your media

Make your media available for diagnosing:

a. Use your own cloud storage provider
b. Use our Dolby Media Input API

a. Use your own cloud storage provider

You will want to consider this option when you move your applications into production. Our services are able to work with many popular cloud storage services such as AWS S3, Azure Blob Storage, GCP Cloud Storage, or your own services with HTTP(s) and basic authentication.

See the Media Input and Output guide for more detail on various storage options.

b. Use the Dolby.io Media Input API (optional)

The Media Input API was designed to give you a quick way to upload media while evaluating Dolby.io Media APIs. We can securely store your media temporarily, any media you upload will be removed regularly so shouldn't be used for permanent storage.

Call Start Media Input to identify a shortcut url. It must begin with dlb:// but otherwise is your own personal unique identifier. Some valid examples:

dlb://example.mp4
dlb://input/your-favorite-podcast.mp4
dlb://usr/home/me/voice-memo.wav

You can think of this like an object key that is used to identify a file for your account. Once you call POST /media/input you'll be returned a new url in the response. This is a pre-signed URL to a cloud storage location you will use to upload the file. You do that by making a PUT request with your media.

import os
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")


# Set or replace this value.
file_path = os.environ["INPUT_MEDIA_LOCAL_PATH"]

# Declare your dlb:// location

url = "https://api.dolby.com/media/input"
headers = {
     "Authorization": "Bearer {0}".format(api_token),
     "Content-Type": "application/json",
     "Accept": "application/json"
}

body = {
    "url": "dlb://in/example.mp4",
}

response = requests.post(url, json=body, headers=headers)
response.raise_for_status()
data = response.json()
presigned_url = data["url"]

# Upload your media to the pre-signed url response

print("Uploading {0} to {1}".format(file_path, presigned_url))
with open(file_path, "rb") as input_file:
  requests.put(presigned_url, data=input_file)

const fs = require("fs")
const axios = require("axios").default

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

// Set or replace this value.
const file_path = process.env.INPUT_MEDIA_LOCAL_PATH

// Declare your dlb:// location

const config = {
  method: "post",
  url: "https://api.dolby.com/media/input",
  headers: {
    "Authorization": `Bearer ${api_token}`,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  data: {
    url: "dlb://in/example.mp4",
  },
}

axios(config)
  .then(function(response) {
    // Upload your media to the pre-signed url response

    const upload_config = {
      method: "put",
      url: response.data.url,
      data: fs.createReadStream(file_path),
      headers: {
        "Content-Type": "application/octet-stream",
        "Content-Length": fs.statSync(file_path).size,
      },
    }
    axios(upload_config)
      .then(function() {
        console.log("File uploaded")
      })
      .catch(function(error) {
        console.log(error)
      })
  })
  .catch(function(error) {
    console.log(error)
  })

# Add your API token as an environmental variable or hard coded value.
API_TOKEN=${DOLBYIO_API_TOKEN:-"your_token_here"}

curl -X POST https://api.dolby.com/media/input \
    --header "Authorization: Bearer $API_TOKEN" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{
        "url": "dlb://in/example.mp4"
    }'

# Use the result in a second command replacing `$PRE_SIGNED_URL` with the response from the previous command:

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

Once the upload is complete, you'll be able to refer to this media with the dlb://in/example.mp4 shortcut.

3. Make an Audio Diagnose request

The Audio Diagnose API API requires an input parameter. There are additional parameters that can be used to customize the results based on the type of content and preferences you might have but we'll keep this example simple.

Regardless of whether you chose to use your own cloud storage or our /media/input service, our API will need to be able to read the media. See the Media Input and Output guide for a more detailed explanation of the various ways you can provide authentication details.

These are all valid input values:

dlb://in/example.mp4
s3://dolbyio/public/shelby/airplane.original.mp4
https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/indoors.original.mp4

Here are some example Audio Diagnose POST requests:

import os
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")

url = "https://api.dolby.com/media/diagnose"
headers = {
    "Authorization": "Bearer {0}".format(api_token),
    "Content-Type": "application/json",
    "Accept": "application/json"
}

body = {
    "input"  : "dlb://in/example.mp3",
}

response = requests.post(url, json=body, headers=headers)
response.raise_for_status()
print(response.json()["job_id"])

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

const axios = require('axios').default;

const config = {
  method: 'post',
  url: 'https://api.dolby.com/media/diagnose',
  headers: {
     "Authorization": `Bearer ${api_token}`,
     "Content-Type": "application/json",
     "Accept": "application/json"
  },
  data: {
    'input': 'dlb://in/example.mp3'
  }
};

axios(config)
  .then(function (response) {
    console.log(response.data.job_id);
  })
  .catch(function (error) {
    console.log(error);
  });

# Add your API token as an environmental variable or hard coded value.
API_TOKEN=${DOLBYIO_API_TOKEN:-"your_token_here"}

curl -X POST "https://api.dolby.com/media/diagnose" \
    --header "Authorization: Bearer $API_TOKEN" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{
        "input": "dlb://in/example.mp3"
    }'

The JSON response will include a unique job_id that you'll need to use to check on the status of media processing.

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

You can explore the Diagnose API reference to learn more about all of the options and response values.

4. Check the job status

It will take a few moments for the API to diagnose your file. You'll need to check the status of the job. You can learn more about this in the How It Works section of the Introduction to learn more.

For this GET /media/diagnose request you'll need to use the job id returned from the previous step. In these examples, it is specified as an environment variable that you'll need to set or replace in the code samples.

import os
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")

url = "https://api.dolby.com/media/diagnose"
headers = {
    "Authorization": "Bearer {0}".format(api_token),
    "Content-Type": "application/json",
    "Accept": "application/json"
}

 # TODO: You must replace this value with the job ID returned from the previous step.

params = {
    "job_id" : os.environ["DOLBYIO_JOB_ID"],
}

response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
print(response.json())

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

const axios = require('axios').default;

const config = {
  method: 'get',
  url: 'https://api.dolby.com/media/diagnose',
  headers: {
     "Authorization": `Bearer ${api_token}`,
     "Content-Type": "application/json",
     "Accept": "application/json"
  },
  
  //TODO: You must replace this value with the job ID returned from the previous step.
  
  data: {
    job_id: process.env.DOLBYIO_JOB_ID
  }
};

axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data, null, 4));
  })
  .catch(function (error) {
    console.log(error);
  });

# Add your API token as an environmental variable or hard coded value.
API_TOKEN=${DOLBYIO_API_TOKEN:-"your_token_here"}

curl -X GET "https://api.dolby.com/media/diagnose?job_id=$DOLBYIO_JOB_ID" \
    --header "Authorization: Bearer $API_TOKEN" \
    
    # TODO: You must replace this value with the job ID returned from the previous step.

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

{
  "path": "/media/diagnose",
  "status": "Running",
  "progress": 42
}

If you re-run and call again after a period of time you'll see the status changes and the result contains the output of Audio Diagnose.

{
  "path": "/media/diagnose",
  "progress": 100,
  "result": {'media_info': {'container': {'kind': 'wav', 'duration': 11.373, ...} 
  "status": "Success"
}