Transcoding Media
Getting Started with the Transcoding Media API
The Dolby.io Media 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 key
- Prepare your media
- Make a Transcode request
- Check the job status
- Download and review media
1. Get your API key
To use the Transcode 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.
Note: Our examples expect you to set the environment variable DOLBYIO_API_KEY with your Media API Key. Alternatively, you can replace the header value for x-api-key directly with your Media API key.
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 request
Next, we will configure our Dolby.io transcode 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
url = "https://api.dolby.com/media/transcode"
headers = {
"x-api-key": os.environ["DOLBYIO_API_KEY"],
"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"])
const axios = require("axios").default
const config = {
method: "post",
url: "https://api.dolby.com/media/transcode",
headers: {
"x-api-key": process.env.DOLBYIO_API_KEY,
"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
curl -X POST "https://api.dolby.com/media/transcode" \
--header "x-api-key: $DOLBYIO_API_KEY" \
--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 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 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
url = "https://api.dolby.com/media/transcode"
headers = {
"x-api-key": os.environ["DOLBYIO_API_KEY"],
"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())
const axios = require("axios").default
const config = {
method: "get",
url: "https://api.dolby.com/media/transcode",
headers: {
"x-api-key": process.env.DOLBYIO_API_KEY,
"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
curl -X GET "https://api.dolby.com/media/transcode?job_id=$DOLBYIO_JOB_ID" \
--header "x-api-key: $DOLBYIO_API_KEY"
# 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
# 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 = {
"x-api-key": os.environ["DOLBYIO_API_KEY"],
"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)
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/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.
curl -X GET https://api.dolby.com/media/output?url="dlb://out/airplane-transcoded.mp4" \
-O -L \
--header "x-api-key: $DOLBYIO_API_KEY"
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 How-to guides here: Transcode API.
Learn more
Updated 18 days ago