Media Input and Output

In order to use Media Processing APIs like Analyze and Enhance you will need to be able to get media in and out of the platform. You do this by specifying a location through the input and output parameters.

This tutorial will guide you through a few of the most common options you have available.

Try It

You may have already discovered the Try It demo. With this method you don't need to call an API at all. You can upload a single media file directly to our site as your input and after analyzing and enhancing your media we will give you back a link to download the media.

If you like what you hear and want to make the API a part of your media workflow or customize the behavior you'll need to use one of the other methods described below.

Dolby Media Input

Dolby has provided /media/input and /media/output APIs you can use to upload and download media. These endpoints are provided as a convenience to get you up and running with 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 IO cloud storage 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 /media/input or using it as the output parameter in a Dolby Media Processing API.

The following steps should illustrate the workflow.

  1. POST /media/input
  2. PUT {url}
  3. Analyze and Enhance
  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. Analyze and Enhance

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.

AWS

Amazon Simple Storage Service (S3) is commonly used in media workflows and provides a security model that allows for collaboration. There are a few ways to share access without exposing your valuable content to the world by generating temporary security credentials.

AWS Tokens

For the input and output parameters you can specify an object dictionary instead of a single string. When you do, you'll include the url as a string but also an auth block where you can identify your access credentials.

{
  "input": {
    "url": "s3://bucket_a/input_file.mp3",
    "auth": {
      "key": "ABCDEIF...ASEOFJHIF",
      "secret": "djkgg39u34i....ogn9gh89w34gh984h",
      "token": "FQggoGZXIvYXdzEgihu9349uf......89234hfhjs+JTpBQ=="
    }
  },
  "output": {
    "url": "s3://bucket_b/output_file.mp3",
    "auth": {
      "key": "ABCDEIF...ASEOFJHIF",
      "secret": "djkgg39u34i....ogn9gh89w34gh984h",
      "token": "FQggoGZXIvYXdzEgihu9349uf......89234hfhjs+JTpBQ=="
    }
  }
}

You can learn more about generating these credentials from the AWS Identity and Access Management documentation.

Pre-Signed URLs

A pre-signed URL from platforms like AWS and GCP can be used as an input and output parameter. These URLs specify a location along with a temporary token that allows our APIs to read/write for that specific storage location.

Here's an example using the AWS SDK in JavaScript:

import aws from 'aws-sdk';

const s3 = new aws.S3({ signatureVersion: "v4",
    secretAccessKey: 'your-secret'
    sessionToken: 'your-token'
    accessKeyId: 'your-key'
    useAccelerateEndpoint: true
  });

  const signed_url = s3.getSignedUrl(action, {
    Bucket: 'your-bucket-name',
    Key: 'your-object-key.mp3',
    Expires: 3600
  });

The signed_url returned can be used for any input and output parameters.

Basic Authentication

To read and write files, the Dolby Media Processing APIs must be able to GET the input location and PUT to the output location. If your input is world readable it should work directly. It is very uncommon to expose a server with an unauthenticated PUT location however so it may be wise to require at least basic authentication credentials.

You can specify these to the Dolby Media Processing APIs by defining an auth block. For example:

{
  "input": "https://your-site.com/public/media.mov",
  "output": {
    "url": "https://your-site.com/api/media-ingest",
    "auth": {
      "username": "me",
      "password": "trust-me"
    }
  }
}

If you are implementing a service to accept these requests you should be aware that you must also accept HEAD requests. The service will first PUT the file to your endpoint and upon completion will expect a response with content-length to verify success.