Music Mastering

Getting Started with the Music Mastering API

Music Mastering API

Getting started

To get started you'll follow these steps.

  1. Get your API key
  2. Prepare your media
  3. Make a Music Mastering request
  4. Check the job status
  5. Download and review the output

1. Get your API key

To use the Music Mastering API, you need an API key. When you sign up for an account, you can retrieve your API key from the Dolby.io dashboard. This unique identifier is passed to all API requests in the x-api-key header.

2. Prepare your media

Make your media available for mastering:

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 basic or token based authentication.

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

b. Use our Dolby Media Input API (optional)

The Media Input API was designed to give you a quick way to upload media while evaluating the 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.

The following examples use an environment variable to identify the api key (DOLBYIO_API_KEY) and the file path to your file (INPUT_MEDIA_LOCAL_PATH). You need to either set those variables for your environment or update the code samples with new values.

import os
import requests

# Set or replace these values

file_path = os.environ["INPUT_MEDIA_LOCAL_PATH"]
api_key = os.environ["DOLBYIO_API_KEY"]

# Declare your dlb:// location

url = "https://api.dolby.com/media/input"
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
    "Accept": "application/json",
}

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

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)
// This example will read a file from your local computer
// and upload it to storage.  You'll need to install node, npm,
// and axios.

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

// Set or replace these values

const file_path = process.env.INPUT_MEDIA_LOCAL_PATH;
const api_key = process.env.DOLBYIO_API_KEY;

// Declare your dlb:// location

const config = {
  method: "post",
  url: "https://api.dolby.com/media/input",
  headers: {
    "x-api-key": api_key,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: {
    url: "dlb://in/example.wav",
  },
};

axios(config)
  .then(function (response) {
    // Upload your media to the pre-signed url response
    console.log(`Upload ${file_path} to ${response.data.url}`);

    const upload_config = {
      method: "put",
      url: response.data.url,
      data: fs.createReadStream(file_path),
      maxContentLength: Infinity,
      maxBodyLength: Infinity,
      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);
  });
curl -X POST https://api.dolby.com/media/input \
    --header "x-api-key: $DOLBYIO_API_KEY" \
    --data '{"url": "dlb://in/example.wav"}'

# 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 $INPUT_MEDIA_LOCAL_PATH

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

3. Make a Music Mastering request

The following examples include using a sample of your music file to preview 3 different music mastering presets. When the preset samples are complete, you can move on to creating a music master with your preferred preset.

After you start a music mastering request, you use the returned job_id to make job status requests. After a Successful job status is returned, you can download and review your music master preview audio file or music master audio file.

3.1 Preview a section of your audio file using three different presets

import os
import requests

# Set or replace these values
api_key = os.environ["DOLBYIO_API_KEY"]
body = {
    "inputs": [
        {"source": "dlb://in/example.wav", "segment": {"start": 10, "duration": 30}}
    ],
    "outputs": [
        {
            "destination": "dlb://out/example-master-preview-a.mp4",
            "master": {"dynamic_eq": {"preset": "a"}},
        },
        {
            "destination": "dlb://out/example-master-preview-b.mp4",
            "master": {"dynamic_eq": {"preset": "b"}},
        },
        {
            "destination": "dlb://out/example-master-preview-c.mp4",
            "master": {"dynamic_eq": {"preset": "c"}},
        },
    ],
}

url = "https://api.dolby.com/media/master/preview"
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
    "Accept": "application/json",
}

response = requests.post(url, json=body, headers=headers)
response.raise_for_status()
print(response.json())
const axios = require("axios").default;

const config = {
  method: "post",
  url: "https://api.dolby.com/media/master/preview",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: {
    inputs: [
      { source: "dlb://in/example.wav", segment: { start: 10, duration: 30 } },
    ],
    outputs: [
      {
        destination: "dlb://out/example-master-preview-a.mp4",
        master: { dynamic_eq: { preset: "a" } },
      },
      {
        destination: "dlb://out/example-master-preview-b.mp4",
        master: { dynamic_eq: { preset: "b" } },
      },
      {
        destination: "dlb://out/example-master-preview-c.mp4",
        master: { dynamic_eq: { preset: "c" } },
      },
    ],
  },
};

axios(config)
  .then(function (response) {
    console.log(response.data.job_id);
  })
  .catch(function (error) {
    console.log(error);
  });
curl -X POST https://api.dolby.com/media/master/preview \
    --header "x-api-key: $DOLBYIO_API_KEY" \
    --data '{
        "inputs": [
            {"source": "dlb://in/example.wav", "segment": {"start": 10, "duration": 30}}
        ],
        "outputs": [
            {
                "destination": "dlb://out/example-master-preview-a.mp4",
                "master": {"dynamic_eq": {"preset": "a"}}
            },
            {
                "destination": "dlb://out/example-master-preview-b.mp4",
                "master": {"dynamic_eq": {"preset": "b"}}
            },
            {
                "destination": "dlb://out/example-master-preview-c.mp4",
                "master": {"dynamic_eq": {"preset": "c"}}
            }
        ]
    }'

Check the job status of the previewed content

You can learn more about this in the How It Works section of the Introduction.

For this GET /media/master/preview request, 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

url = "https://api.dolby.com/media/master/preview"
headers = {
    "x-api-key": os.environ["DOLBYIO_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}

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

response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
print(response.json())
const axios = require("axios").default;

const config = {
  method: "get",
  url: "https://api.dolby.com/media/master/preview",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  params: {
    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);
  });
curl -X GET "https://api.dolby.com/media/master/preview?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/master/preview",
  "status": "Running",
  "progress": 42
}

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 download.

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

Download the completed previews

import os
import shutil
import requests

output_path = os.environ["PREVIEW_A_MEDIA_LOCAL_PATH"]

url = "https://api.dolby.com/media/output"
headers = {
    "x-api-key": os.environ["DOLBYIO_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}

preview_url = "dlb://out/example-master-preview-a.mp4"

args = {"url": preview_url}

with requests.get(url, params=args, headers=headers, stream=True) as response:
    response.raise_for_status()
    response.raw.decode_content = True
    print("Downloading from {0} into {1}".format(response.url, output_path))
    with open(output_path, "wb") as output_file:
        shutil.copyfileobj(response.raw, output_file)
const fs = require("fs");
const axios = require("axios").default;

const output_path = process.env.PREVIEW_A_MEDIA_LOCAL_PATH;

const config = {
  method: "get",
  url: "https://api.dolby.com/media/output",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  responseType: "stream",
  params: { url: "dlb://out/example-master-preview-a.mp4" },
};

axios(config)
  .then(function (response) {
    response.data.pipe(fs.createWriteStream(output_path));
    response.data.on("error", function (error) {
      console.log(error);
    });
    response.data.on("end", function () {
      console.log("File downloaded!");
    });
  })
  .catch(function (error) {
    console.log(error);
  });
# 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.
 
curl -X GET -G https://api.dolby.com/media/output \
    --data-urlencode 'url=dlb://out/example-master-preview-a.mp4' \
    -o $PREVIEW_A_MEDIA_LOCAL_PATH \
    -L \
    --header "x-api-key: $DOLBYIO_API_KEY"

3.2 Create a music master

import os
import requests

# Set or replace these values
api_key = os.environ["DOLBYIO_API_KEY"]
body = {
    "inputs": [{"source": "dlb://in/example.wav"}],
    "outputs": [
        {
            "destination": "dlb://out/example-mastered.wav",
            "master": {"dynamic_eq": {"preset": "c"}},
        }
    ],
}

url = "https://api.dolby.com/media/master"
headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
    "Accept": "application/json",
}

response = requests.post(url, json=body, headers=headers)
response.raise_for_status()
print(response.json())
const axios = require("axios").default;

const config = {
  method: "post",
  url: "https://api.dolby.com/media/master",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: {
    inputs: [{ source: "dlb://in/example.wav" }],
    outputs: [
      {
        destination: "dlb://out/example-mastered.wav",
        master: { dynamic_eq: { preset: "c" } },
      },
    ],
  },
};

axios(config)
  .then(function (response) {
    console.log(response.data.job_id);
  })
  .catch(function (error) {
    console.log(error);
  });
curl -X POST https://api.dolby.com/media/master \
    --header "x-api-key: $DOLBYIO_API_KEY" \
    --data '{
        "inputs": [{"source": "dlb://in/example.wav"}],
        "outputs": [
            {
                "destination": "dlb://out/example-mastered.m4a",
                "master": {"dynamic_eq": {"preset": "c"}}
            }
        ]
    }'

Check the job status of the music master

You can learn more about this in the How It Works section of the Introduction.

For this GET /media/master request, 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

url = "https://api.dolby.com/media/master"
headers = {
    "x-api-key": os.environ["DOLBYIO_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}

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

response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
print(response.json())
const axios = require("axios").default;

const config = {
  method: "get",
  url: "https://api.dolby.com/media/master",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  params: {
    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);
  });
curl -X GET "https://api.dolby.com/media/master?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/master",
  "status": "Running",
  "progress": 42
}

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 download.

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

Download the completed music master

import os
import shutil
import requests

output_path = os.environ["OUTPUT_MEDIA_LOCAL_PATH"]

url = "https://api.dolby.com/media/output"
headers = {
    "x-api-key": os.environ["DOLBYIO_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}

args = {"url": "dlb://out/example-mastered.wav"}

with requests.get(url, params=args, headers=headers, stream=True) as response:
    response.raise_for_status()
    response.raw.decode_content = True
    print("Downloading from {0} into {1}".format(response.url, output_path))
    with open(output_path, "wb") as output_file:
        shutil.copyfileobj(response.raw, output_file)
const fs = require("fs");
const axios = require("axios").default;

const output_path = process.env.OUTPUT_MEDIA_LOCAL_PATH;

const config = {
  method: "get",
  url: "https://api.dolby.com/media/output",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  responseType: "stream",
  params: {
    url: "dlb://out/example-mastered.wav",
  },
};

axios(config)
  .then(function (response) {
    response.data.pipe(fs.createWriteStream(output_path));
    response.data.on("error", function (error) {
      console.log(error);
    });
    response.data.on("end", function () {
      console.log("File downloaded!");
    });
  })
  .catch(function (error) {
    console.log(error);
  });
# 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.
 
curl -X GET "https://api.dolby.com/media/output?url=dlb://out/example-mastered.wav" \
    -O -L \
    --header "x-api-key: $DOLBYIO_API_KEY"

Learn more


Did this page help you?