Dolby.io Media Temporary Cloud Storage

Temporary and quick process to upload media while evaluating the Dolby.io Media APIs

Dolby Media Input and Output

📘

Temporary Storage

The Media Input and Media Output APIs described on this page with dlb:// urls were created for an extra convenience in building a prototype or proof of concept. Any data stored with Dolby.io is temporary and will be removed. For production use cases you should choose your preferred storage provider.

The /media/input and /media/output endpoints allow you to upload and download media. These APIs are intended to be helpful in building a prototype or proof-of-concept.

A few key points:

  • Temporary: The media you store with these APIs is temporary and will
    automatically be removed within 24 - 48 hours.

  • Secure: The media is stored in an isolated location that only you can access with your API key. It is encrypted at rest and while in transit with https. Access to the production system is controlled and audited to prevent unauthorized use.

The dlb:// URI Scheme

By convention all files using Media Input and Output are identified with the URI scheme dlb://. Everything that follows that prefix can be thought of as an object key that uniquely identifies a media object. This object key is unique to your account API key and can mirror your media workflow preferences.

For example, each of these would be a valid location:

  • dlb://input.wav
  • dlb://output.wav
  • dlb://usr/home/media/in/foo.mp3
  • dlb://usr/home/media/out/foo.enhanced.mp3

We recommend sticking with typical alpha-numeric characters.

Creating a dlb:// Location

A dlb:// url can be created by calling POST /media/input or using it as the output parameter in a Dolby.io Media API.

The following steps should illustrate the workflow.

  1. POST /media/input
  2. PUT {url}
  3. Call another Dolby.io Media API
  4. GET /media/output

1. POST /media/input

The /media/input resource is used to declare a dlb:// path. For example, the request might look like this:

import os
import requests

input_path = os.environ["INPUT_MEDIA_LOCAL_PATH"]

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

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

response = requests.post(url, json=body, headers=headers)
response.raise_for_status()
data = response.json()
presigned_url = data["url"]
print("Uploading {0} to {1}".format(input_path, presigned_url))
with open(input_path, "rb") as input_file:
    requests.put(presigned_url, data=input_file)
const fs = require('fs');
const axios = require('axios').default;

const file_path = process.env.INPUT_MEDIA_LOCAL_PATH;

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

axios(config)
    .then(function (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);
    });
curl  -X POST https://api.dolby.com/media/input \
      --header "x-api-key: $DOLBYIO_API_KEY" \
      --data '{
          "url": "dlb://example/input.wav"
          }'

At this step you haven't stored your file yet, so far this just prepares a pre-signed url you can use to upload the file.

2. PUT {url}

In the previous step you should be returned a response that includes a long URL.

{"url":"https://bucket.s3.zone.amazonaws.com/89056194-5ca3-4c87-aecc-ab6ebf6e3f6b/example1/input.wav?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA2N2ZL3VQMRYUK3KH%2F20190815%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20190815T222328Z&X-Amz-Expires=3600&X-Amz-Security-Token=FQoGZXIvYXdzELD%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDFLozcz8MJRNQ03UqyLIA28mAc8gx%2F1a2R3es%2BZQjxBLGTn1D6XITL5vOx91YHfvP7TR06FEyeSKecQQRs%2BDxy3wZ7ZjXvEaS61KhiVh1xBMn%2FdfuhH1F8%2BzoA5ZdaPKG%2BJgTfu2eSpJ0zG9nmcAP6FVRBpa67aztimBw7qUTwDm9GinJwTpa9jxOCPOjiCiGFSkuJmWXiwwgNhdF2jrCWgAUUD0lEYQcDnc2CAQkCYPTRRioBTIeecsjG5BJDN7X0TeEAj68TxQ7UmcjMFojpn2EIs6H%2FhVGeDXYIPqSrEXQsUe6fNlWrFeN4Io4D11ffsPC31Hs9G9TzzIlpgmjr4FeIwB304J3v3yitfGGBMQBGVlXUGqiiMhcEYUXItMJP8UxuNnP4VxlX39jntDg5LI%2FPUJroWbsftTxYc43rLFDhE87X9AJdtQqwT77sFBTVagpuC1Cee6sQ6RNwqRbRQHvbBTCYfy7P13O%2BdHk0GoFr%2FDlKHB1GSzw2GODFjNmrKiSCRPr2yMV04yR60G0xmWHAa%2Fm8bPO1rKh3Ox0ypWirRNlwPLgknsoqk5yzBPS40RUpbYETVADOz%2FyRBkkmOxCmF6yBd%2Bazb25Fx%2FnLrygwjccTdC0CjgttfqBQ%3D%3D&X-Amz-Signature=e96512d4154987fd347d725f6661363b9641026312e99e9ae6707b55f838423e&X-Amz-SignedHeaders=host"}'

You can begin uploading your media by running an HTTP PUT request to
this pre-signed URL with your media file as the payload. Depending on the size of the file, this step can take a few moments.

curl  -X PUT $PRE_SIGNED_URL -T ./input.wav

Your dlb:// name will be typically maintained for a period of 24-48 hours but this pre-signed url is only valid for a short period of time.

3. Call another Media API

Now you can begin to analyze and enhance your media. The Dolby Media APIs
can accept the dlb:// url as either input or output in requests.

Your input should have been created as a result of the first two steps. Your output can be generated on the fly as a result of running an API such as /media/enhance.

For example:

import os
import requests

# Set or replace these values
api_key = os.environ['DOLBYIO_API_KEY']
body = {
  "input" : "dlb://example/input.wav",
  "output" : "dlb://example/output.wav",
}

url = "https://api.dolby.com/media/enhance"
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/enhance",
  headers: {
    "x-api-key": process.env.DOLBYIO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  data: {
    input: "dlb://example/input.wav",
    output: "dlb://example/output.wav",
  },
}

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/enhance \
     --header "x-api-key: $DOLBYIO_API_KEY" \
     --data '{
         "input": "dlb://example/input.wav",
         "output": "dlb://example/output.wav"
     }'

Note in this example, the URL dlb://example/output.wav does not yet exist, but will be created as a result of running the /media/enhance process.

4. GET /media/output

To retrieve the file stored at a dlb:// URL, you can use the /media/output API. You can do this with a GET request that provides a redirect to download the binary file.

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",
}

# To download the enhanced file, 
#     set the url to "dlb://out/example-enhanced.mp3",
# To download the results of analyze API, 
#     set the url to "dlb://out/example-metadata.json",

args = {
    "url": "dlb://out/example-enhanced.mp3",
}

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',
    // To download the enhanced file, 
    //     set the url to "dlb://out/example-enhanced.mp3",
    // To download the results of analyze API, 
    //     set the url to "dlb://out/example-metadata.json",

    params: {
        url: 'dlb://out/example-enhanced.mp3'
    }
};

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);
    });
curl  -X GET https://api.dolby.com/media/output?url=dlb://example/output.wav \
      --header "x-api-key: $DOLBYIO_API_KEY" \
      -L -O

You specify the -L because the service redirects 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.

API Reference

See the API Reference for more information on these services.


Did this page help you?