Real-time Streaming

The Dolby.io Communications APIs support real-time streaming (RTS) to broadcast conferences to up to 100k viewers over real-time WebRTC using Dolby.io Real-Time Streaming services (formerly Millicast). Dolby.io Real-time Streaming provides sub-second latency streaming around the globe, compared to traditional HLS that has 15-30 second latency. Integrated with the Dolby.io Communications APIs, conferences can expand real-time viewership to large global audiences, enabling the ability to interact without delay. Dolby.io Real-time Streaming also provides a pre-built, embeddable player that is compatible with all devices and browsers. For more information on advanced streaming control, see the Streaming Client SDK.

The Start Real-time Streaming REST API uses the mixer layout to broadcast a simulcast (multi-bitrate) transmission ensuring viewers receive the appropriate quality depending on their connection. The mixer renders the conference and sends a single stream; the bandwidth sent is approximately 2.5 Mbps.

You can use the Monitor API to retrieve a detailed summary of the streamed conference; the mixerRtsStreaming field in this report can be used to calculate the cost.

Note: Dolby.io Real-time Streaming usage and billing is separate from the Dolby.io Communications APIs and Dolby.io Media APIs billing system. If you exceed the free tier for streamed minutes, you must upgrade your streaming account. You can use the provided pricing calculator to determine the pricing plan that best fits your use case.

To estimate your bandwidth usage:

(# of Viewers + 1) x 0.019GB (Gigabytes per minute) = bandwidth consumed

Note: The +1 denotes the mixer broadcasting the conference to the Dolby.io Real-time Streaming platform.

This guide walks you through accessing your RTS account, setting up a stream, and using the RTS REST API to broadcast to the hosted Millicast player in a web browser.

Create a stream token

Real-time streaming a Dolby.io conference requires the STREAM NAME and the PUBLISHING TOKEN parameters that are available in the Dolby.io dashboard of your Dolby.io Real-time Streaming account. Using these parameters, you can call the RTS REST APIs to start or stop streaming to an ingest endpoint, and use the Stream.Rts.StatusUpdated webhook to monitor streaming events.

1. Log into the Dolby.io dashboard.

2. Navigate to the Streaming tab and click the + button in the Live Broadcast tab to add a new token.

11771177

3. Give your token a label and select the number of stream names to add. For simplicity, set the Secure Viewer setting to NO RESTRICTION and click OK.

502502

4. Open the created token and select the API tab.

14531453

5. Locate and copy the STREAM NAME and the PUBLISHING TOKEN.

For more information on creating, renewing, and deleting tokens, see Managing Your Tokens.

Authentication

In order to start and stop the live stream, you will need to make REST API calls from your backend. Since each call to the REST API requires authentication, you must first request an access token from the Authorization REST API. Locate the App key and App secret from your Dolby.io dashboard and use the pair for the Authorization header of the HTTP call. For more information, see Application Credentials.

import requests

url = "https://api.dolby.io/v1/auth/token"

payload = "grant_type=client_credentials"
headers = {
    "accept": "application/json",
    "Cache-Control": "no-cache",
    "Content-Type": "application/x-www-form-urlencoded",
    "authorization": "Basic base64(APP_KEY + ":" + APP_SECRET)"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'Cache-Control': 'no-cache',
    'Content-Type': 'application/x-www-form-urlencoded',
    authorization: 'Basic base64(APP_KEY + ":" + APP_SECRET)'
  },
  body: new URLSearchParams({grant_type: 'client_credentials'})
};

fetch('https://api.dolby.io/v1/auth/token', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
curl --request POST \
     --url https://api.voxeet.com/v1/auth/token \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic base64(APP_KEY + ":" + APP_SECRET)' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials

The response to this call will be a JWT token that contains the access token to use for all the following REST API calls.

Starting the live stream

The Start Real-time Streaming REST API requires the conference ID that you want to stream, the STREAM NAME, and the PUBLISHING TOKEN.

To start the live stream to the ingest endpoint, send a POST request to the Start Real-time Streaming REST API using the access token for authorization.

The following are examples of the REST API call:

import requests

url = "https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/start"

payload = {
    "streamName": "{stream_name}",
    "publishingToken": "{publishing_token}"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
    "authorization": "Bearer {bearer_token}"  
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer {bearer_token}'
  },
  body: JSON.stringify({streamName: '{stream_name}', publishingToken: '{publishing_token}'})
};

fetch('https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/start', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
curl --request POST \
     --url https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/start \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {bearer_token}' \
     --header 'content-type: application/json'
     --data '
{
     "streamName": "{stream_name}",
     "publishingToken": "{publishing_token}"
}
'

A few seconds after calling the API, you will be able to see the live stream starting using the hosted player from Dolby.io Real-time Streaming available at the URL listed under HOSTED PLAYER PATH, for example https://viewer.millicast.com/v2?streamId=accountId/streamName.

To be informed once the status of the real-time stream changes, your application can subscribe to the Stream.RTS.Status.Updated webhook event. When you receive this event, you can take action on what to do and what to present to your audience.

Stopping the live stream

If you need to stop the live stream before the conference ends, call the Stop Real-time Streaming REST API:

import requests

url = "https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/stop"

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer {bearer_token}"
}

response = requests.post(url, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer {bearer_token}'
  }
};

fetch('https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/stop', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
curl --request POST \
     --url https://comms.api.dolby.io/v2/conferences/mix/{conference_id}/rts/stop \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {bearer_token}' \
     --header 'content-type: application/json'