The Dolby.io Transcode API is designed to convert your media from one format to another.

This tutorial shows you the end-to-end process of how to use the Media Transcode API so that you can start to convert your media to popular formats playable in browsers and on mobile devices.

Getting started

To get started you'll follow these steps.

Get your API token
Prepare your media
Make a Transcode API request
Check the job status
Download and review media

1. Get your API token

To use the Transcode API, you need an API token. To learn more about how to get an API token, see API Authentication.

2. Prepare your media

To use the Transcode API, you first need to have a media input file where Dolby.io can access it. Your options include:

a. A publicly accessible file on the internet.
b. Use your own cloud storage provider.
c. Use our Dolby temporary storage via the Media Input and Output.

In this getting started example, we'll use a publicly accessible video for our input and write the output to Dolby temporary storage. Temporary storage is meant as a way to quickly get up-and-running with our APIs without configuring your own storage. Once you're production-ready you will want to utilize your own cloud storage.

For more on how to use your own storage with Dolby.io, read our guides on AWS S3, Azure Blob Storage, GCP Cloud Storage, or use your own services with basic or token-based authentication.

3. Make a Transcode API request

Next, we will configure our Transcode API request to use a simple case asking for a basic "mp4" output. Dolby.io will make some decisions for you about the most compatible kind of video and audio codecs to use. You can always configure these yourself later!

import os
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")

url = "https://api.dolby.com/media/transcode"
headers = {
    "Authorization": "Bearer {0}".format(api_token),
    "Content-Type": "application/json",
    "Accept": "application/json"
}

body = {
    "inputs": [{ "source" : "https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/indoors.original.mp4"}],
    "outputs": [
        {
            "id" : "my_mp4",
            "destination" : "dlb://out/airplane-transcoded.mp4",
            "kind" : "mp4"
        }
    ]
}

try:
    response = requests.post(url, json=body, headers=headers)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    raise Exception(response.text)
print(response.json()["job_id"])

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

const axios = require("axios").default
const config = {
    method: "post",
    url: "https://api.dolby.com/media/transcode",
    headers: {
        "Authorization": `Bearer ${api_token}`,
        "Content-Type": "application/json",
        "Accept": "application/json"
    },
    data: {
        inputs : [ { "source" : "https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/indoors.original.mp4"} ],
        outputs: [
            {
                "id" : "my_mp4",
                "destination" : "dlb://out/airplane-transcoded.mp4",
                "kind" : "mp4"
            }
        ]
    }
}
axios(config)
    .then(function(response) {
        console.log(response.data.job_id)
    })
    .catch(function(error) {
        console.log(error)
    })

#!/bin/bash

# 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/transcode" \
    --header "Authorization: Bearer $API_TOKEN" \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{
        "inputs": [{ "source" : "https://dolbyio.s3-us-west-1.amazonaws.com/public/shelby/indoors.original.mp4"}],
        "outputs": [
            {
                "id" : "my_mp4",
                "destination" : "dlb://out/airplane-transcoded.mp4",
                "kind" : "mp4"
            }
        ]
    }'

After you start a Transcode API request, you use the returned job_id. You can use this job ID to query the status of your job.

4. Check the job status

Transcoding is an asynchronous process. Once you have the job_id from submitting your Transcode API request, you'll need to check the status of the job. You can learn more about this in the How It Works section of the Introduction.

Here is an example API call to check our status. This is a GET /media/transcode request. You will need to replace the job_id with the value returned from the previous step.

import os
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")

url = "https://api.dolby.com/media/transcode"
headers = {
    "Authorization": "Bearer {0}".format(api_token),
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# TODO: You must replace this value with the job ID returned from the previous step.

params = {
    "job_id": "12345678-d7eb-4012-9b46-0fa5ae6011f3"
}

try:
    response = requests.get(url, params=params, headers=headers)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    raise Exception(response.text)
print(response.json())

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

const axios = require("axios").default

const config = {
  method: "get",
  url: "https://api.dolby.com/media/transcode",
  headers: {
    "Authorization": `Bearer ${api_token}`,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  
  //TODO: You must replace this value with the job ID returned from the previous step.
  
  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)
  })

#!/bin/bash

# Add your API token as an environmental variable or hard coded value.
API_TOKEN=${DOLBYIO_API_TOKEN:-"your_token_here"}

curl -X GET "https://api.dolby.com/media/transcode?job_id=$DOLBYIO_JOB_ID" \
    --header "Authorization: Bearer $API_TOKEN" \
    
    # TODO: You must replace this value with the job ID returned from the previous step.

While the job is still in progress, you will be able to see the status and progress values returned.

{
  "path": "/media/transcode",
  "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 from our temporary storage.

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

5. Download and review media

Once media transcoding is complete, the file exists in the output location specified when the job was started, in our case: dlb://out/example_transcoded.wav.

import os
import shutil
import requests

# Add your API token as an environmental variable or hard coded value.
api_token = os.getenv("DOLBYIO_API_TOKEN", "your_token_here")

# define where to output our downloaded file (for example "~/Desktop/example_transcoded.mp4")
output_path = os.environ["OUTPUT_MEDIA_LOCAL_PATH"]

url = "https://api.dolby.com/media/output"
headers = {
    "Authorization": "Bearer {0}".format(api_token),
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# specify which file we are downloading from temporary storage
params = {
    "url": "dlb://out/airplane-transcoded.mp4",
}

with requests.get(url, params=params, 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)

// Add your API token as an environmental variable or hard coded value.  
const api_token = process.env.DOLBYIO_API_TOKEN || "your_token_here"  

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: {
    "Authorization": `Bearer ${api_token}`,
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  responseType: "stream",
  params: {
    url: "dlb://out/airplane-transcoded.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. 
# The `-O` is to just output the file to your local system with the same filename.

# Add your API token as an environmental variable or hard coded value.
API_TOKEN=${DOLBYIO_API_TOKEN:-"your_token_here"}

curl  -X GET https://api.dolby.com/media/output?url="dlb://out/airplane-transcoded.mp4" \
      -O -L \
      --header "Authorization: Bearer $API_TOKEN" \

And that's it! Simply open the output file in the audio player of your choice. From here, there is a lot more you can do. Be sure to check out our Transcode API how-to guides.

Learn more

Media Transcode API Guide

Learn how the Media Transcode API can transcode your media.

API Reference

Open API Specification to explore the parameters and responses.