NEWDolby Media Processing APIs are now the Dolby.io Media APIs Learn More >
X

Media Input and Output

The Dolby.io Media APIs need to be able to read your media and have a storage location to write output in order to process it. You can use many popular cloud services such as AWS S3, GCP Cloud Storage, Azure Blob Storage, or others when specifying the input and output parameters in your Dolby.io Media API requests.

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 will have access to 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:

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
very long looking 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, a request such as this:

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 which will provide a redirect to download the binary file.

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