Analyzing Media

The Dolby Media Analyze API is designed to give insight into your media. By providing diagnostic information about media format, content analysis, loudness conformance, and a quality assessment for your audio you can build a range of applications.

To get started without writing any code, you can use the Try It Yourself demo and view the Analyze API output for your own media file. If you are ready for the next step to analyze 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 Analyze request
  4. Check the results
  5. Learn more

This analysis is useful for applications such as podcasts, online learning, healthcare conferencing, or video sharing. You'll be able to identify silence, audio clipping, noise level, and more.

1. Get Your API Key

To use the Analyze 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 Analyze Request

The Analyze API only requires the input parameter to begin analyzing your media. You'll use the url shortcut from the previous step to get started. Depending on the size of your media it can take some time to fully diagnose audio issues 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/analyze \
     --header "x-api-key: $DOLBYIO_API_KEY" \
     --data '{
         "input": "dlb://in/example.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 analysis, your job will go through a few statuses 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/analyze?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/analyze",
  "status": "Running",
  "progress": 0
}

If you re-run and call again after a period of time you'll see the status changes and the results of your analysis will be in the result JSON response. Here's an example of what analysis can return:

{
  "path": "/media/analyze",
  "progress": 100,
  "result": {
    "audio": {
      "bandwidth": 10687,
      "clipping": {
        "first_event": 31.547541666666667,
        "num_events": 1
      },
      "loudness": {
        "gating_mode": "speech",
        "measured": -20.55,
        "range": 5.85,
        "sample_peak": 0,
        "true_peak": 0.01
      },
      "noise": {
        "level_average": -64.72,
        "snr_average": 41.99
      },
      "silence": {
        "end": 0,
        "num_sections": 0,
        "start": 0.02,
        "total": 0
      },
      "validation": {
        "loudness": {
          "detail": "measured loudness exceeds maximum specified (-20.55 > -22);measured true peak exceeds maximum specified (0.01 > -2)",
          "pass": false
        }
      }
    },
    "media_info": {
      "audio": {
        "bitrate": 256001,
        "channel_order": "L R",
        "channels": 2,
        "codec": "aac",
        "duration": 97.685,
        "sample_rate": 48000
      },
      "container": {
        "bitrate": 1651700,
        "duration": 97.685,
        "kind": "mp4",
        "size": 20168287
      },
      "video": {
        "bitrate": 1391583,
        "codec": "h264",
        "duration": 97.685,
        "frame_rate": 25,
        "height": 720,
        "width": 1280
      }
    }
  },
  "status": "Success"
}

Learn More

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