Analyze Loudness

The Dolby.io Analyze API can be used to get information about the loudness of a media file. This can be useful for quality control workflows.

Request

Loudness details for your media are returned from a basic request to analyze.

# 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/analyze \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "input": "dlb://in/example.mp3",
    "output": "dlb://out/example.analysis.json"
  }'

Response

Sample output from a request to the Analyze API on a mono audio file:

{
  "processed_region": {
    "audio": {
      "loudness": {
        "gating_mode": "speech",
        "measured": -20.55,
        "range": 5.85,
        "sample_peak": 0,
        "true_peak": 0.01,
        "time_series": [
          [0.0, -120.0, -12.5, -12.19],
          [1.0, -120.0, -12.5, -12.37],
          [2.0, -23.02, -12.5, -12.17]
        ]
      }
    }
  }
}

The data returned in this sample indicate the dialog/speech loudness using a speech gating mode is -20.55 LKFS and has a range of 5.85 LU. The sample peak is 0 dBFS and the true peak is 0.01 dBTP.

A time series of loudness values every sec is also generated. This is useful to help understand how the loudness changes over time. The following values are returned in the time series:

• time
• ungated loudness
• sample peak
• true peak

Loudness Parameters

Some of the parameters you can use to change how loudness is measured.

metering_mode

The metering_mode specifies the perception model to use. It can be any one of the ITU-R BS.1770 models mentioned earlier.

• "1770-1"
• "1770-2"
• "1770-3"
• "1770-4"

dialog_intelligence

If you want to disable Dolby Dialog Intelligence algorithms and dialog-gated loudness metering you can set this value to false. When disabled, the loudness estimate will be level-gated.

speech_threshold

When dialog_intelligence is enabled you can control the speech_threshold for determining whether a segment is classified as dialog or not. This value is specified as a percentage from 0 to 100 with the default value of 15%. That means if dialog is recognized to be greater than 15% it will be classified as dialog and be dialog gated while anything less will be ungated.

Loudness Validation

Loudness validation can check if the audio conforms with a specific loudness profile. The loudness profile can be specified as in the input parameters. Additional loudness constraints may be provided for custom requirements. You can find the available pre-defined options in the Loudness table.

Sample Request

Here's an example for how to do a simple validation test for conformance to the published loudness standards for Amazon's platform:

# 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/analyze \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
  "input": "dlb://in/example.mp3",
  "output": "dlb://out/example.analysis.json"
  "loudness": {
    "profile": "service_amazon"
    }
  }'

Custom Loudness Profile

You can specify your own custom profile for validation as well.

# 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/analyze \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{
    "input": "dlb://in/example.mp3",
    "output": "dlb://out/example.analysis.json",
    "loudness": {
      "profile": "custom",
      "custom": {
        "metering_mode": "1770-2",
        "dialog_intelligence": true,
        "speech_threshold": 50
      }
    },
    "validation": {
      "loudness": {
        "loudness_max": -20
      }
    }
  }'

In the output, you will find a pass/fail validation result to help give insight into how to correct the issue. For example the Analyze API may return the following output:

{
  "processed_region": {
    "audio": {
      "validation": {
        "loudness": {
          "detail": "measured loudness exceeds maximum specified (-20.55 > -22); measured true peak exceeds maximum specified (0.01 > -2)",
          "pass": false
        }
      }
    }
  }
}

If you media doesn't pass validation, you can use the Enhance API to correct it.